# 社保

**Repository Path**: saulCode/social-security

## Basic Information

- **Project Name**: 社保
- **Description**: tlns-项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel → 飞书多维表格 自动导入工具

轻量网页:上传社保/工资 Excel(支持跨列合并大标题)→ 自动识别字段 → 写入飞书多维表格。

## 原理
1. 用 openpyxl 把**合并单元格填满**(跨列大标题的值复制到同组各格)。
2. 为每一列拼出「大标题 - 子字段」签名(如 `养老保险 - 汇缴基数`),相邻重复自动去重。
3. 把签名与飞书字段名(去空格后)做匹配 → 认出每一列对应的目标字段。
   **列位置怎么变都不怕,只要表头文字含义一致就能认出来。**
4. 读数据行 → 按字段类型转换 → 调飞书 Base API 批量写入(每批 200 条)。

## 运行前必做(一次性)
应用 `cli_aaaa77967b619cbc` 必须拥有该多维表格的**编辑权限**,否则写入会报 403:
- 打开多维表格 → 右上角「共享 / 协作者」→ 添加协作者,搜索该应用 → 角色选「可编辑」。

## 安装与运行
```bash
pip install -r requirements.txt
python app.py
# 默认监听 0.0.0.0:8000,浏览器打开 http://<服务器IP>:8000
```

## 配置
应用内已内置默认凭证与表信息,也可用环境变量覆盖(更推荐,避免把 secret 写进代码):
- `FEISHU_APP_ID`、`FEISHU_APP_SECRET`
- `PORT`(监听端口,默认 8000)
- `BASE_TOKEN`、`TABLE_ID` 在 `app.py` 顶部常量修改

目标字段列表 `FIELDS` 在 `app.py` 中维护,顺序即写入顺序,与 Excel 列位置无关。
若表头行数变化,改 `HEADER_ROWS` / `DATA_START_ROW`。

## 生产部署(推荐 gunicorn)
```bash
pip install gunicorn
gunicorn -w 2 -b 0.0.0.0:8000 app:app
```
如需域名/HTTPS,在前面加一层 Nginx 反向代理即可。

## 排错
- 上传后提示「应用没有编辑权限」→ 按上面「运行前必做」给应用加编辑角色。
- 页面显示「未匹配字段」→ 到 `app.py` 的 `FIELDS` 与 Excel 表头核对(可跑 `inspect_excel.py` 看每列签名)。
- 数字变成文本 → 多维表格对应字段当前是「文本」类型,属正常;如需数值汇总可在飞书把该列改成「数字」类型,程序会按类型自动转换。