@lark-apaas/coding-steering 0.1.6-alpha.8 → 0.1.6-beta.0

package/steering/nestjs-react-fullstack/skills/server-builtins-file-storage-service/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: server-builtins-file-storage-service
+description: "Use when server-side code needs to upload or download files programmatically, such as file format conversion, automated report generation, or background tasks that produce files. NOT for frontend file operations. 触发词：服务端文件上传, 服务端文件下载, FileService, nestjs file, 后端文件处理, 文件格式转换, 生成文件上传"
+steering: true
+steering-topic: server_builtins_file_storage_service
+match-template-name: nestjs-react-fullstack
+---
+
+# NestJS File Service SDK
+
+在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
+
+> **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
+> CLI 调试场景请参考 `file-storage` skill。
+
+## 使用场景
+
+| 场景 | 说明 |
+|------|------|
+| 服务端文件处理 | 下载文件到本地处理后重新上传，如图片格式转换、docx 格式转换等 |
+| 自动化任务生成文件 | 定时任务或事件触发后，根据数据库/插件内容生成文件并上传，如定时生成 PDF 报告、图片海报等 |
+
+## Quick Reference
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `upload(file, options?)` | 上传文件 | `FileMeta` |
+| `download(path)` | 下载文件（≤50MB） | `FileDownloadBuilder` |
+| `remove(filePaths)` | 删除文件 | `RemoveResponse` |
+| `getFileMetadata(filePath)` | 获取文件元信息 | `FileMeta` |
+
+## 注入 FileService
+
+```typescript
+import { FileService } from '@lark-apaas/fullstack-nestjs-core';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly fileService: FileService) {}
+}
+```
+
+## 公共类型
+
+```typescript
+interface FileMeta {
+  id: string;
+  name: string;
+  filePath: string;
+  metadata: { contentLength: string; mimeType: string };
+  downloadURL: string;
+  createdAt: string;
+  updatedAt: string;
+  bucketID: string;
+}
+```
+
+## 核心操作
+
+### 1. 上传文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `file` | `FileBody` | 是 | 文件内容（支持 `Buffer`、`ReadableStream`、`ArrayBuffer`、`Blob`、`string` 等） |
+| `options` | `UploadOptions` | 否 | 上传选项 |
+
+**UploadOptions：**
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `fileName` | `string` | 否 | 文件名称 |
+| `contentType` | `string` | 否 | MIME 类型 |
+| `cacheControl` | `string \| number` | 否 | 缓存控制 |
+| `upsert` | `boolean` | 否 | 是否覆盖已有文件 |
+
+**返回值：** `FileMeta`
+
+**示例：**
+
+```typescript
+// 基本上传
+const result = await this.fileService.upload(buffer);
+
+// 带选项上传
+const result = await this.fileService.upload(fileBody, {
+  fileName: 'report.pdf',
+  contentType: 'application/pdf',
+  upsert: false,
+});
+```
+
+### 2. 下载文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `path` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值 `DownloadResult`：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `Blob`（默认）/ `ReadableStream`（流式） | 文件内容 |
+| `metadata` | `FileMeta` | 文件元信息 |
+
+> **推荐始终使用 `.asStream()`**，避免大文件导致内存溢出。直接 `await download()` 有 50MB 限制。
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL + 流式下载
+const downloadURL = fileMeta.downloadURL; // 从上传返回值或数据库获取
+const { content, metadata } = await this.fileService
+  .download(downloadURL)
+  .asStream();
+
+// 也可以使用文件存储路径
+const { content, metadata } = await this.fileService
+  .download('file.pdf')
+  .asStream();
+
+// 不推荐：Blob 下载（限制 50MB，会将整个文件加载到内存）
+const { content, metadata } = await this.fileService.download(downloadURL);
+```
+
+### 3. 删除文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePaths` | `string[]` | 是 | downloadURL 或文件存储路径数组 |
+
+**返回值：** `FileMeta[]` - 删除成功的文件元信息数组
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const result = await this.fileService.remove([fileMeta.downloadURL]);
+
+// 也可以使用文件存储路径
+const result = await this.fileService.remove(['file1.pdf', 'file2.png']);
+```
+
+### 4. 获取文件元信息
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePath` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值：** `FileMeta | null` - 文件元信息或 `null` 表示文件不存在或删除失败
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const meta = await this.fileService.getFileMetadata(fileMeta.downloadURL);
+
+// 也可以使用文件存储路径
+const meta = await this.fileService.getFileMetadata('file.pdf');
+```
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 直接 `await download()` 导致内存溢出 | 始终使用 `.asStream()` 流式下载 |
+| 忘记设置 `contentType` 导致浏览器无法预览 | 上传时明确指定 `contentType` |
+| 直接 `new FileService()` 手动实例化 | 通过 NestJS DI 注入 `FileService` |
+| 在异步回调中调用 `download()` 导致上下文丢失 | 在请求处理函数中立即调用，SDK 内部已处理上下文捕获 |
+| 删除时传单个字符串 | `remove()` 参数为 `string[]` 数组 |

package/steering/nestjs-react-fullstack/skills/trigger-guide/SKILL.md

@@ -86,6 +86,7 @@ interface WebhookEvent {
 ```
 
 ### 指定值限制
+
 1. Webhook 触发器不可以设置指定值，并且告知用户。
 
 ### 代码示例

package/steering/nestjs-react-fullstack/skills/user-identity/SKILL.md

@@ -208,6 +208,7 @@ const UserInfoPanel = () => {
 ```
 
 **注意**：
+
 - `lark_user_id` 通过额外异步请求获取，可能晚于 `user_id` 等基础字段就绪
 - 请求失败或用户无对应飞书账号时值为 `undefined`，**必须用条件渲染**
 - `useCurrentUserProfile()` 的返回值里**不存在** `open_id`、`feishu_id`、`openId` 字段——在这个 Hook 的消费代码里飞书 ID 唯一字段名是 `lark_user_id`（仅约束本 Hook；项目其他场景调 spark `id_convert` / 通讯录 API 出现 `open_id` 是正常的）

package/steering/nestjs-react-fullstack/skills/user-management-best-practices/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: user-management-best-practices
+description: "Use when 决定是否创建用户表、选择用户唯一标识（user_id vs email/手机号）、设计 user_profile 字段与 UNIQUE 约束、处理防重复提交/upsert 去重，或涉及问卷、抽奖、报名、投票等用户提交场景的表结构设计。触发词：用户管理, 用户表设计, user_id, email, user_profile, 去重, 防重复提交, 批量导入用户, upsert, UNIQUE约束, UserSelect, UserDisplay, user management, deduplication"
+steering: true
+steering-topic: user_management_best_practices
+match-template-name: nestjs-react-fullstack
+---
+
+# 用户管理最佳实践指南
+
+## 概述
+
+本指南适用于生成涉及用户管理、问卷、抽奖、报名、投票等用户提交场景的代码。
+
+**核心问题：**
+
+- 妙搭 Agent 无法获取企业的所有用户数据，需要构建应用维度的用户表
+- 企业无法显式感知飞书的 user_id（不透明的数字字符串，如 "1847292357012580"），无法批量导入飞书用户到应用的用户表
+- 推荐使用邮箱或者手机号作为业务层唯一标识（不是 user_id）
+- UserSelect 返回的 IUserProfile 对象已包含 email 和 phone_number 字段，可直接使用
+
+**本指南解决：**
+
+- 何时使用 UserSelect 组件 vs 何时创建用户表
+- 如何设计用户业务表（正确的唯一约束）
+- 防止重复提交的正确实现方式
+
+---
+
+## 核心原则：禁止事项
+
+| 禁止操作                              | 说明                                                   | 正确做法                                                                                     |
+| ------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| 不推荐实现批量导入用户的功能          | Agent 无法获取企业全量用户，批量 INSERT users 表行不通 | 推荐使用 UserSelect 组件动态选择用户                                                         |
+| 不推荐用 user_id 作为去重逻辑         | 企业不感知飞书用户 id，无法感知是谁                    | 使用 email 或者手机号做唯一约束（UNIQUE(email)），不要使用姓名，可能会重复                   |
+| 禁止编造 user_id                      | Mock 数据中不能随意编造 user_id 值                     | 必须使用 SQL skill 规定的测试用户列表                                                        |
+| 禁止全量查询用户列表                  | 全量拉取数据会导致接口超时或 OOM                       | 使用后端分页查询（skip/take）                                                                |
+| 禁止前端分页用户列表                  | 前端分页需要全量拉取数据，导致性能问题                 | 使用后端分页，前端仅控制页码                                                                 |
+| 禁止只存 user_id 不存 email or 手机号 | 业务层无法用 user_id 做防重和查询                      | 存储 user_profile 字段（已包含 email/phone），并在表中单独添加 email 或 phone 列用于唯一约束 |
+
+---
+
+## 决策树示例：何时创建用户表 vs 何时使用 user_profile
+
+```text
+需要记录用户相关业务数据？
+    │
+    ├─ 仅需要识别"谁"执行操作（发帖人、评论者）
+    │   └─ ✅ 直接使用 user_profile 类型字段
+    │       示例：posts.author（user_profile）
+    │
+    └─ 需要存储业务特定的用户数据
+        │
+        ├─ 数据与具体业务资源强绑定（问卷提交、抽奖记录）
+        │   └─ ✅ 创建业务表 + user_profile 字段 + email 唯一约束
+        │       示例：questionnaire_responses (id, respondent, email, UNIQUE(questionnaire_id, email))
+        │
+        └─ 数据代表"用户在系统中的身份"（员工、学生、会员）
+            └─ ✅ 创建人员实体表，user_profile 作为主键
+                示例：employees (employee_profile PRIMARY KEY, department, position)
+```
+
+---
+
+## 用户列表查询与性能注意事项
+
+### UserSelect vs 分页列表的选择
+
+根据场景选择正确的用户选择方式：
+
+| 场景               | 使用组件         | 数据加载方式 | 典型数量 |
+| ------------------ | ---------------- | ------------ | -------- |
+| 表单选择用户       | UserSelect       | 搜索驱动     | 1-10     |
+| 用户管理后台       | Table + 后端分页 | 分页加载     | 100+     |
+| 问卷提交记录列表   | Table + 后端分页 | 分页加载     | 100+     |
+| 抽奖参与者名单展示 | Table + 后端分页 | 分页加载     | 100+     |
+
+- **UserSelect 组件**：搜索驱动，返回完整 IUserProfile 对象（含 email、phone_number）。详细用法参考 **client-builtins-user-service**
+- **Table + 后端分页**：详细实现参考 **table-skill**
+
+### 分页实现
+
+用户列表必须使用后端分页，禁止前端全量拉取。具体实现参考 **table-skill**。
+
+### 动态创建用户记录
+
+**何时动态创建：**
+
+1. **首次提交场景**：用户首次提交问卷/参与抽奖时，使用 `upsert` 方法
+2. **首次登录场景**：用户首次登录系统时，创建用户记录
+
+## 常见错误速查表
+
+| 错误模式                | 问题                   | 正确做法                                                     | 影响        |
+| ----------------------- | ---------------------- | ------------------------------------------------------------ | ----------- |
+| 批量 INSERT users       | Agent 无法获取全量用户 | 使用 UserSelect 组件                                         | 🔴 CRITICAL |
+| `UNIQUE(user_id)`       | 企业不认识 user_id     | `UNIQUE(email)`                                              | 🔴 CRITICAL |
+| 编造 user_id            | Mock 数据无效          | 使用测试用户列表                                             | 🔴 CRITICAL |
+| 全量查询用户列表        | 接口超时或 OOM         | 使用后端分页（skip/take）                                    | 🔴 CRITICAL |
+| 前端分页（全量拉取）    | 首次加载超时           | 使用后端分页                                                 | 🔴 CRITICAL |
+| 只存 user_id 不存 email | 无法做业务层防重       | 存储 user_profile（已含 email），并添加 email 列用于唯一约束 | 🟠 BUG      |
+| 直接显示 user_id        | 用户体验差             | 使用 UserDisplay 组件                                        | 🟡 UX       |
+| 创建 users 基础表       | 无法同步飞书数据       | 使用 user_profile 类型                                       | 🟠 DESIGN   |
+
+## 相关技能参考
+
+- **client-builtins-user-service**: UserSelect 详细用法、IUserProfile 类型定义、UserDisplay 组件、useCurrentUserProfile hook
+- **sql**: user_profile 类型约束、JSONB 验证规则、测试用户列表
+- **table-skill**: Table 组件使用、后端分页实现、前端分页最佳实践
+- **authz-guide**: 结合基于角色的访问控制（如：只允许用户查看/编辑自己的提交）
+
+## 自查清单
+
+### 表设计
+
+- [ ] 判断是否需要创建用户表（参考决策树）
+- [ ] 人员实体表使用 `user_profile PRIMARY KEY`
+- [ ] 业务表使用 `id UUID PRIMARY KEY` + `user_profile` 字段
+- [ ] 业务表包含 `email VARCHAR(255)` or `phone VARCHAR(255)` 字段
+- [ ] 设置了正确的唯一约束（使用 email or 手机号，如 `UNIQUE(resource_id, email)`）
+
+### 前端实现
+
+- [ ] 使用 UserSelect 组件而非手动输入
+- [ ] 使用 UserDisplay 展示用户（不直接显示 user_id）
+- [ ] 用户列表使用后端分页（不全量拉取）
+- [ ] Table 组件的 onChange 触发后端请求
+
+### 后端实现
+
+- [ ] Entity 定义了正确的唯一约束（`@Unique(['resourceId', 'email'])` or `@Unique(['resourceId', 'phone'])`）
+- [ ] 错误处理包含唯一约束冲突（409 Conflict）
+- [ ] 存储 user_profile 字段（已包含 email/phone）
+- [ ] 在表中单独添加 email 或 phone 列，用于唯一约束和索引查询
+- [ ] 列表接口使用 skip/take 分页查询
+- [ ] 返回 pagination 对象（page, pageSize, total）
+
+### Mock 数据
+
+- [ ] user_id 使用测试用户列表（不编造）
+- [ ] user_profile 中的 email/phone 与 user_id 对应正确
+- [ ] 测试了重复提交场景（唯一约束生效）

package/steering/nestjs-react-fullstack/skills_local/code-fix/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: code-fix
-description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions (traceid troubleshooting), production log troubleshooting that should route through miaoda-cli, route 404 errors, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, traceid, 线上日志, 线上日志查询, 查询线上日志, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错
-steering: true
-steering-topic: code_fix
-match-template-name: nestjs-react-fullstack
+description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions, route 404 errors, PostgresError connection verification failed, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错, please re-obtain a valid database connection
 ---
 
 
@@ -70,7 +67,7 @@ import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
 
 1. **不确定就查**：图标名不在你已知列表里 → 先 `Read packages/client/lucide-react/iconMappings.json`（或 lucide-react 包的 d.ts 导出列表）确认存在，再写 import
 2. **替换图标必须连同 import 列表一起检查**：把旧图标替换成新图标时，**必须先 grep 当前文件 import 列表**确认新名未已 import，避免触发 LSP "标识符重复" / `no-redeclare`
-3. **LSP 警告是硬约束**：multi_edit / 写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误跑 `commit_task`
+3. **LSP 警告是硬约束**：写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误提交
 
 ### 同名 export 重复（修复 SOP）
 
@@ -82,30 +79,38 @@ import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
 2. 预防规则（跨子组件常量前缀化、行内/桶导出二选一）见 `coding-guide` 的「TypeScript 规范 · 命名约定」与「文件命名约定 · 导入导出」
 
 ### 前端 Dto 类型使用错误
+
 **问题描述**：代码中使用的 Dto 类型属性与实际定义不一致，导致 TypeScript 类型检查报错
 
 **核心原则**：遇到类型错误，先查 `@client/src/api/gen/types.gen.ts` 确认定义，再修改代码
 
 **错误示例**：
+
 - 示例1： 赋值时缺失必需属性
+
 ```
 Property 'dueDate' is missing in type {...} but required in type 'CreateBorrowRecordDto'
 ```
 
 - 示例2：访问不存在的属性
+
 ```
 Property 'avatar' does not exist on type 'LotteryParticipantResponseDto'
 ```
 
 - 示例3：导入不存在的类型
+
 ```
 Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponseDto'
 ```
+
 **解决步骤**：
+
 1. 在 `@client/src/api/gen/types.gen.ts` 中搜索目标Dto实际定义
 2. 确认类型名称是否正确，明确完整定义
 
 **检查清单**：
+
 - [ ] 已查看 `@client/src/api/gen/types.gen.ts` 中的类型定义
 - [ ] 已对比代码使用与实际定义的差异
 - [ ] 已根据实际定义修正代码
@@ -156,22 +161,11 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 
 ## 调用生成的 API 异常
 
-### 需要查询线上日志时使用 miaoda-cli
-
-**适用场景**：仅当用户提供 traceid、logid、线上报错、发布错误日志、线上运行日志、线上链路追踪，或排查必须依赖线上前端/后端日志。
+### 查看本地运行日志
 
-**处理要求**：引导并使用 `miaoda-cli` skill 查询线上日志。优先通过 `miaoda observability log/trace` 查询线上运行日志与链路追踪；排查发布错误时使用 `miaoda deploy error-log`。本地开发日志、构建日志、测试日志、浏览器控制台日志不在此范围内，按当前技能或对应工具排查。拿到线上日志后再回到本技能继续定位与修复代码问题。
+**适用场景**：本地开发期 API 调用异常、控制台报错、后端进程行为异常。
 
-### 用户提供了 traceid，排查错误
-
-**解决方案**：使用 `miaoda-cli` skill 读取线上前端与后端日志，获取详细错误
-
-**排查示例**：
-
-用户输入：8ae6724e-277e-4d51-afbf-b524b654f27f 看看这个 trace 为什么报错了
-排查路径：
-1. 使用 `miaoda-cli` skill 查询线上服务端与 trace 日志
-2. 根据服务端日志中对应的日志内容修复对应代码逻辑
+**处理要求**：本地日志由 `scripts/dev.js` 落到 `logs/` 目录(`dev.log`、`server.log` 及对应的 `.std.log`),直接 `cat` / `tail -F` 查看;浏览器侧错误看 DevTools Console。本地版**不接管线上日志/traceid 排查链路**(那条路径由发布平台和 oncall 工具承接)。
 
 ### 调用 API 客户端时后端返回异常
 
@@ -195,25 +189,45 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 错误信息：服务内部错误
 错误堆栈（可选）：Error: 这是测试异常：HelloController.getConfig方法故意抛出的错误\n    at HelloController.getConfig (/home/gem/workspace/dist/server/modules/hello/hello.controller.js:17:15)\n    at /home/gem/workspace/node_modules/@nestjs/core/router/router-execution-context.js:38:29\n    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
 
-2. 如果错误堆栈存在，优先按照错误堆栈中的相关文件与行列号找到对应文件，读取内容并启发式分析
-3. 如果错误堆栈不存在，按照请求的 URL 找到对应的 controller，检查其中的逻辑，启发式的分析依赖。如发现问题可以直接处理。若仍未发现问题，可以在 controller 抛出的错误对象上增加 `message` 属性，改变 message 内容方便 debug。你可以在增加完之后让用户重新请求触发问题。
+1. 如果错误堆栈存在，优先按照错误堆栈中的相关文件与行列号找到对应文件，读取内容并启发式分析
+2. 如果错误堆栈不存在，按照请求的 URL 找到对应的 controller，检查其中的逻辑，启发式的分析依赖。如发现问题可以直接处理。若仍未发现问题，可以在 controller 抛出的错误对象上增加 `message` 属性，改变 message 内容方便 debug。你可以在增加完之后让用户重新请求触发问题。
 
 ```typescript
 try {
-	// some logic
+ // some logic
 } catch (err) {
         // 后端异常必须在后端打印日志
-	this.logger.error('...')
-   	// 后端异常同时需要抛出到前端，方便修复
-	// 构造为 http-errors compatible 的对象
-   	err.statusCode = 500;
-   	err.message = err.stack; // 抛出 stack 信息，保障有足够的错误内容透出
-   	throw err;
+ this.logger.error('...')
+    // 后端异常同时需要抛出到前端，方便修复
+ // 构造为 http-errors compatible 的对象
+    err.statusCode = 500;
+    err.message = err.stack; // 抛出 stack 信息，保障有足够的错误内容透出
+    throw err;
 }
 ```
 
 注意：优先让错误信息中包含堆栈信息，以更精确的定位错误发生位置。
 
+## 数据库连接问题
+
+### PG 连接串过期 / 失效
+
+**问题描述**：`npm run dev` 启动后，后端访问数据库时报类似如下错误（关键特征是 `connection verification failed` + `expired or invalid connection link`，endpoint 域名以实际为准）：
+
+```
+PostgresError: connection verification failed for endpoint "<pg-endpoint>": expired or invalid connection link, please re-obtain a valid database connection
+```
+
+**根因**：PG connection string 注入在 `.env.local` 中，由于安全策略，连接串 **5 天过期**。`npm run dev` 启动时只会读取一次 `.env.local`，过期后旧连接串就会触发上述报错。
+
+**修复方案**：**重新运行 `npm run dev`** 即可。启动脚本会重新拉取并注入最新的 PG connection string 到 `.env.local`，新进程读取到的就是有效连接串。不要去改后端代码或 ORM 配置。
+
+**注意**：
+
+- 不要尝试手工编辑 `.env.local` 里的 PG connection string，连接串由启动流程统一管理
+- 不要把这个错误当成业务代码 bug 去排查 controller / service / 数据库 schema
+- 重启 `npm run dev` 后若仍报同样错误，再按其它通用排查路径处理
+
 ## 路由和导航问题
 
 ### 路由 404 错误诊断