# KK

**Repository Path**: xxq_cube/kk

## Basic Information

- **Project Name**: KK
- **Description**: KK
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KK OA 退换货数据 → 飞书多维表格 同步工具

自动从 KK OA 系统抓取退换货申请数据，同步到飞书多维表格。

## 功能特点

- **自动化登录**：支持验证码 OCR 识别，Cookie 持久化复用
- **全量/增量同步**：支持全量拉取或增量更新
- **智能匹配**：以申请单号为主键，自动判断新增或更新
- **变更通知**：同步完成后推送飞书消息通知
- **容错机制**：API 限流自动重试，页面解析降级方案

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
playwright install chromium
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，填写实际配置：

```bash
cp .env.example .env
```

### 3. 运行同步

```bash
# 增量同步（默认）
python -m kk_feishu_sync.main

# 全量同步
python -m kk_feishu_sync.main --mode full

# 调试模式
python -m kk_feishu_sync.main --log-level DEBUG
```

## 配置说明

### 飞书应用配置

1. 在 [飞书开放平台](https://open.feishu.cn/) 创建企业自建应用
2. 添加权限：`bitable:app`、`im:message`
3. 获取 App ID 和 App Secret

### 飞书表格配置

1. 创建多维表格，包含以下字段：
   - 申请单号（文本，主键）
   - 申请日期（日期）
   - 申请类型（单选：退货/换货）
   - 客户名称（文本）
   - 客户编码（文本）
   - 产品名称（文本）
   - 产品编码（文本）
   - 数量（数字）
   - 金额（数字）
   - 退货原因（文本）
   - 审批状态（单选）
   - 审批人（文本）
   - 处理结果（文本）
   - 处理日期（日期）
   - 最后同步时间（文本）

2. 从表格 URL 获取 App Token 和 Table ID：
   ```
   https://xxx.feishu.cn/base/xxx?table=tblxxxx
                              ^^^^^^^^       ^^^^^^
                              App Token      Table ID
   ```

## 项目结构

```
KK_feishu/
├── kk_feishu_sync/
│   ├── __init__.py      # 包初始化
│   ├── config.py        # 配置管理
│   ├── auth.py          # KK OA认证模块
│   ├── fetcher.py       # 退换货数据抓取
│   ├── sync.py          # 飞书同步逻辑
│   ├── feishu.py        # 飞书API封装
│   ├── main.py          # 主入口
│   └── logger.py        # 日志配置
├── .env.example         # 配置示例
├── requirements.txt     # 依赖清单
└── README.md            # 说明文档
```

## 定时任务

### Windows（任务计划程序）

```
schtasks /create /tn "KK_Feishu_Sync" /tr "python -m kk_feishu_sync.main" /sc daily /st 09:00
```

### Linux（crontab）

```bash
# 每天早上9点执行
0 9 * * * cd /path/to/KK_feishu && python -m kk_feishu_sync.main >> logs/cron.log 2>&1
```

## 常见问题

### Q: 验证码识别失败？

A: 确保已安装 ddddocr 的依赖：
```bash
# Windows
pip install ddddocr
# 如果提示缺少 VC++ 运行库，安装：
# https://aka.ms/vs/17/release/vc_redist.x64.exe
```

### Q: 登录失败？

A: 检查 KK OA 的登录页面结构，可能需要调整 `auth.py` 中的：
- 输入框选择器（`input[name="username"]` 等）
- 验证码图片选择器（`img.code-image` 等）
- 登录按钮选择器

### Q: 数据抓取为空？

A: 检查 `fetcher.py` 中的：
- API 接口名称（当前默认 `returnList` 或 `findPage`）
- 页面 URL 是否正确
- 是否需要切换 tab 或点击查询按钮

### Q: 飞书同步失败？

A: 检查飞书应用权限和表格字段名是否与配置一致。

## 开发说明

如需调整字段映射，修改以下文件：
- `config.py`：字段名配置
- `fetcher.py`：API 返回字段解析（`_parse_api_data` 函数）
- `sync.py`：字段构建逻辑（`_build_fields` 函数）

## License

MIT