# dingtalk-ainotable

**Repository Path**: anning233/dingtalk-ainotable

## Basic Information

- **Project Name**: dingtalk-ainotable
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-22
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 钉钉AI表格数据同步系统

一个基于钉钉开放平台的AI表格（多维表）数据同步和管理系统，包含后端API服务和前端管理界面。

## 📋 项目概述

本项目旨在提供完整的钉钉AI表格数据操作解决方案，支持数据的增删改查、数据表管理、字段管理等功能。系统采用前后端分离架构，后端提供RESTful API，前端提供用户友好的管理界面。

## 🏗️ 项目架构

```
dingtalk-ainotable/
├── dingtalk-background/     # 后端API服务
│   ├── routes/             # 路由模块
│   ├── services/           # 业务逻辑服务
│   ├── utils/              # 工具函数
│   ├── prisma/             # 数据库模型
│   └── data/               # 数据文件
├── dingtalk-frontend/       # 前端管理界面
│   ├── src/                # 源代码
│   └── public/             # 静态资源
└── README.md               # 项目文档
```

## ✨ 主要功能

### 后端功能
- 🔐 **AccessToken管理** - 自动获取、缓存和刷新钉钉访问令牌
- 📊 **AI表格操作** - 完整的CRUD操作支持
- 🗂️ **数据表管理** - 创建、删除、重命名数据表
- 📝 **字段管理** - 动态创建、更新、删除字段
- 📄 **记录管理** - 批量插入、更新、删除记录
- 🔍 **数据查询** - 支持复杂条件查询和分页
- 🔄 **数据同步** - MySQL数据库同步功能
- 📈 **健康监控** - 服务状态监控和日志记录

### 前端功能
- 🎨 **现代化UI** - 基于Vue 3 + PrimeVue的响应式界面
- 📋 **表单管理** - 产品配置表单
- 🔧 **实时配置** - 动态配置管理
- 📱 **移动适配** - 支持移动端访问

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- npm >= 8.0.0
- MySQL >= 8.0 (可选，用于数据同步功能)

### 安装步骤

1. **克隆项目**
```bash
git clone https://gitee.com/anning233/dingtalk-ainotable.git
cd dingtalk-ainotable
```

2. **配置环境变量**
```bash
# 复制环境变量模板
cp dingtalk-background/env.example dingtalk-background/.env

# 编辑配置文件，填入您的钉钉应用信息
vim dingtalk-background/.env
```

3. **安装后端依赖**
```bash
cd dingtalk-background
npm install
```

4. **安装前端依赖**
```bash
cd ../dingtalk-frontend
npm install
```

5. **启动服务**

启动后端服务：
```bash
cd dingtalk-background
npm run dev  # 开发模式
# 或
npm start    # 生产模式
```

启动前端服务：
```bash
cd dingtalk-frontend
npm run dev
```

## ⚙️ 配置说明

### 环境变量配置

在 `dingtalk-background/.env` 文件中配置以下参数：

```env
# 钉钉应用配置
DINGTALK_APP_KEY=your_app_key
DINGTALK_APP_SECRET=your_app_secret
DINGTALK_OPERATOR_ID=your_operator_id
DINGTALK_NOTABLE_BASE_ID=your_base_id

# 服务器配置
PORT=3000
```

### 钉钉应用配置

1. 登录[钉钉开发者后台](https://open.dingtalk.com/)
2. 创建企业内部应用
3. 获取 `AppKey` 和 `AppSecret`
4. 配置回调地址和权限范围
5. 获取操作员的 `UnionId`

## 📚 API文档

### 基础接口

- `GET /health` - 健康检查
- `GET /` - 服务信息

### 钉钉相关接口

- `GET /api/dingtalk/token` - 获取访问令牌
- `POST /api/dingtalk/token/refresh` - 刷新访问令牌
- `GET /api/dingtalk/token/status` - 令牌状态检查

### AI表格操作接口

#### 数据表管理
- `GET /api/notable/sheets` - 获取所有数据表
- `POST /api/notable/sheets` - 创建数据表
- `PUT /api/notable/sheets/:id` - 更新数据表
- `DELETE /api/notable/sheets/:id` - 删除数据表

#### 字段管理
- `GET /api/notable/fields` - 获取所有字段
- `POST /api/notable/fields` - 创建字段
- `PUT /api/notable/fields/:id` - 更新字段
- `DELETE /api/notable/fields/:id` - 删除字段

#### 记录管理
- `GET /api/notable/records` - 查询记录
- `POST /api/notable/records` - 批量插入记录
- `PUT /api/notable/records` - 批量更新记录
- `DELETE /api/notable/records` - 批量删除记录

## 🛠️ 开发指南

### 项目结构说明

#### 后端项目结构
```
dingtalk-background/
├── app.js                 # 应用入口文件
├── config.js              # 配置文件
├── routes/                # 路由模块
│   ├── dingtalk.js        # 钉钉API路由
│   ├── notable.js         # AI表格操作路由
│   ├── business.js        # 业务逻辑路由
│   └── mysqlSync.js       # 数据同步路由
├── services/              # 业务服务层
│   ├── dingtalkNotableService.js
│   └── mysqlSyncService.js
├── utils/                 # 工具函数
│   └── tokenCache.js      # 令牌缓存管理
└── prisma/                # 数据库模型
    └── schema.prisma
```

#### 前端项目结构
```
dingtalk-frontend/
├── src/
│   ├── components/        # Vue组件
│   │   └── ProductConfigForm.vue
│   └── main.js           # 应用入口
├── index.html            # HTML模板
└── vite.config.js        # Vite配置
```

### 开发命令

#### 后端开发
```bash
cd dingtalk-background
npm run dev      # 开发模式，支持热重载
npm start        # 生产模式
npm run health   # 健康检查
```

#### 前端开发
```bash
cd dingtalk-frontend
npm run dev      # 开发服务器
npm run build    # 构建生产版本
npm run preview  # 预览构建结果
npm run lint     # 代码检查
```

## 🔧 技术栈

### 后端技术
- **Node.js** - 运行时环境
- **Express.js** - Web框架
- **Prisma** - 数据库ORM
- **MySQL2** - MySQL数据库驱动
- **Axios** - HTTP客户端
- **Helmet** - 安全中间件
- **Morgan** - 日志中间件
- **CORS** - 跨域支持

### 前端技术
- **Vue 3** - 前端框架
- **Vite** - 构建工具
- **PrimeVue** - UI组件库
- **PrimeIcons** - 图标库
- **Axios** - HTTP客户端
- **TypeScript** - 类型支持

## 📝 使用示例

### 获取访问令牌
```javascript
const response = await fetch('/api/dingtalk/token');
const data = await response.json();
console.log(data.access_token);
```

### 查询AI表格记录
```javascript
const response = await fetch('/api/notable/records', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    baseId: 'your_base_id',
    sheetId: 'your_sheet_id',
    filter: {
      combination: 'and',
      conditions: [
        {
          field: 'name',
          operator: 'equal',
          value: ['张三']
        }
      ]
    }
  })
});
```

## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- 项目维护者：[您的姓名]
- 邮箱：[您的邮箱]
- 项目地址：[项目链接]

## 🙏 致谢

感谢钉钉开放平台提供的API支持，以及所有开源项目的贡献者们。

---

**注意**: 请确保在生产环境中妥善保管您的钉钉应用密钥和敏感信息，不要将其提交到版本控制系统中。