常见问题

本文档引用文件

• README.md
• package.json
• codegen/package.json
• deno/package.json
• pc/package.json
• uni/package.json
• codegen/src/config.ts
• deno/graphql.config.js
• pc/graphql.config.js
• uni/graphql.config.js

目录

1. 环境配置
2. 代码生成
3. API调用
4. 权限控制
5. 部署发布
6. 数据库相关
7. 性能优化
8. 安全问题
9. 故障排除

环境配置

本项目采用多模块架构，包含 codegen、deno（后端）、pc（前端管理界面）、uni（移动端）等子项目，均通过 pnpm 进行包管理。

如何正确安装依赖？

根据 package.json 中的 postinstall 脚本，项目在安装依赖后会自动为各子项目执行 pnpm install。

解决方案：

1. 确保已安装 pnpm（推荐使用 npm install -g pnpm）
2. 在项目根目录执行：

npm install

该命令会触发根目录的 postinstall 钩子，自动为 deno、pc、uni 三个子项目安装依赖。

常见问题：

• 若提示 only-allow pnpm 错误，请使用 pnpm install 替代 npm install
• 若出现编译依赖问题（如 ssh2），请确保系统已安装 Python、C++ 构建工具

Section sources

• package.json
• deno/package.json
• pc/package.json
• uni/package.json

如何配置开发环境变量？

项目使用 .env 文件管理环境变量。各子项目需在各自目录下创建 .env 文件。

关键环境变量示例：

# deno/.env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=nest_db
GRAPHQL_PATH=/graphql

Section sources

• deno/package.json

代码生成

本项目核心特性是可增量更新的代码生成器，解决了传统代码生成器覆盖修改代码的问题。

代码生成器如何工作？

根据 README.md 描述，代码生成器利用 git diff 和 git apply 技术实现增量更新：

1. 首次生成代码后，手动修改部分文件
2. 再次运行代码生成器时，系统会：
   • 记录已生成代码的原始版本
   • 比对当前代码与原始版本的差异（git diff）
   • 生成新代码后，将之前的修改合并进来（git apply）
3. 实现"生成代码 + 手动开发"的无缝结合

命令：

npm run codegen

Section sources

• README.md
• package.json
• codegen/package.json

如何添加新的数据表并生成代码？

1. 在 codegen/src/tables 目录下创建表定义文件（如 my_table.ts）
2. 定义表结构：

export const my_table = {
  name: 'my_table',
  columns: [
    { name: 'id', type: 'uuid', primaryKey: true },
    { name: 'name', type: 'string', length: 100 }
  ]
};

3. 运行代码生成：

npm run codegen

4. 系统将自动生成：
   • Deno 后端：DAO、Model、Resolver、Service
   • PC 前端：Vue 页面、路由、API 调用
   • UniApp 移动端：页面和 API

Section sources

• codegen/src/tables/tables.ts
• codegen/src/template

API调用

项目采用 GraphQL 作为主要 API 通信协议，前后端均通过 GraphQL 进行数据交互。

如何调用 GraphQL API？

前端调用示例（PC 项目）：

// src/utils/graphql.ts
import { request } from 'graphql-request';

const API_URL = '/graphql';

export const gqlQuery = (query, variables = {}) => {
  return request(API_URL, query, variables);
};

// 使用示例
const GET_USERS = `query GetUsers($page: Int) {
  usr_page(page: $page, size: 20) {
    records {
      id
      name
      email
    }
    total
  }
}`;

gqlQuery(GET_USERS, { page: 1 }).then(data => {
  console.log(data.usr_page.records);
});

自动生成的 API 文件：

• pc/src/components/Api.ts
• pc/src/layout/Api.ts
• uni/src/pages/[[table]]/Api.ts

Section sources

• pc/src/utils/graphql.ts
• deno/gen/graphql.ts
• pc/src/components/Api.ts

如何添加新的 GraphQL 查询？

1. 在 deno/src 相应模块中修改 Resolver
2. 或通过代码生成器自动创建
3. 运行 npm run gqlgen 生成 TypeScript 类型：

npm run gqlgen

该命令会根据 GraphQL Schema 自动生成前端可用的 TypeScript 类型。

Section sources

• package.json
• deno/package.json
• deno/lib/script/graphql_codegen_config.ts

权限控制

系统提供多层次的权限管理机制。

字段级权限如何配置？

通过 npmFieldPermit 工具生成字段权限配置：

npm run field_permit

该命令分析代码中的字段使用情况，生成 field_permit 相关配置，实现字段级别的读写控制。

相关文件：

• deno/gen/base/field_permit/*
• pc/src/store/field_permit.ts

菜单权限如何扫描？

使用 permit_scan.js 工具自动扫描前端路由和组件中的权限标识：

npm run permit

该工具会：

1. 扫描 pc/src/views 目录下的所有 Vue 文件
2. 提取权限标识（如 @permit("user:create")）
3. 生成权限配置供后端验证

Section sources

• package.json
• pc/package.json
• pc/src/utils/permit_scan.js

部署发布

如何构建生产环境版本？

后端（Deno）：

npm run build-prod

该命令调用 deno run -A ./lib/script/build.ts --target linux --env prod，使用 Deno 打包为可执行文件。

前端（PC）：

cd pc && npm run build-prod

使用 Vite 构建生产版本，输出到 dist 目录。

发布到服务器：

npm run publish

调用 deno/lib/script/publish.js，通过 SSH 将构建产物部署到目标服务器。

Section sources

• package.json
• deno/package.json
• pc/package.json

数据库相关

如何初始化数据库？

npm run initdb

该命令执行 codegen/src/util/npmInitDB.ts，根据表定义自动创建数据库表结构。

如何导入 CSV 数据？

npm run importCsv

执行 npmImportCsv.ts 脚本，将 CSV 文件数据导入指定数据表。

如何修改数据库字符集？

npm run db_charset

执行 npmDbCharset.ts 脚本，统一数据库字符集为 UTF8MB4。

Section sources

• package.json
• codegen/src/util/npmInitDB.ts
• codegen/src/util/npmImportCsv.ts
• codegen/src/util/npmDbCharset.ts

性能优化

如何提升构建性能？

1. 增加 Node.js 内存限制：在 package.json 的构建脚本中设置 NODE_OPTIONS=--max-old-space-size=4096
2. 使用增量构建：Vite 和 Deno 均支持快速热重载
3. 依赖预构建：pnpm 的 onlyBuiltDependencies 配置确保关键依赖预构建

// pc/package.json
"pnpm": {
  "onlyBuiltDependencies": [
    "@parcel/watcher",
    "esbuild",
    "vue-demi"
  ]
}

GraphQL 查询优化

1. 避免过度获取：只请求需要的字段
2. 使用分页：大数据集使用 page 和 size 参数
3. 启用缓存：对静态数据启用 Redis 或内存缓存

Section sources

• pc/package.json
• deno/package.json

安全问题

密码如何加密？

使用 npmPassword.ts 工具生成加密密码：

npm run pwd

系统采用 MD5 + 盐值 的方式存储密码，实际项目中建议升级为 bcrypt 或 Argon2。

如何生成加密密钥？

npm run db_gen_crypto_key

该命令生成用于数据加密的密钥，存储在数据库中，用于敏感字段的加密存储。

Section sources

• package.json
• deno/package.json
• codegen/src/util/npmPassword.ts
• deno/lib/script/db_gen_crypto_key.ts

故障排除

数据库连接失败

可能原因：

1. 数据库服务未启动
2. 连接参数错误（host、port、user、pass）
3. 防火墙阻止连接

解决方案：

1. 检查 deno/.env 文件中的数据库配置
2. 使用 MySQL 客户端测试连接
3. 确认数据库允许远程连接

GraphQL 查询返回空数据

1. 检查 Resolver 中的数据库查询逻辑
2. 确认用户具有相应数据权限
3. 查看后端日志是否有错误信息

代码生成器不生效

1. 确认 codegen 目录下的表定义文件语法正确
2. 检查是否有 TypeScript 编译错误
3. 确认 __out__ 目录有写入权限

前端无法加载

1. 确认 pc 项目的依赖已正确安装
2. 检查 Vite 配置是否正确
3. 查看浏览器控制台是否有 JavaScript 错误

Section sources

• README.md
• deno/.env
• pc/src/utils/request.ts