# 月度结薪完整流程（含坑点回顾）

> 5 月跑通后请回流到本文档，把新经验记录下来。

## 完整步骤

### 0. 前置检查

```bash
# 确认本月账务目录存在
ls ~/Downloads/大梦N月账务处理/

# 必须有:
#   考勤表/                          ← 各种考勤资料
#   大梦可能实验室_N月营收分析_*.xlsx    ← 营收分析（用户预先生成）
#   大梦_可能实验室_西湖店__店内订单明细*.xlsx
#   大梦_可能实验室_滨江店__店内订单明细*.xlsx
#   大梦可能实验室（西湖店）_全渠道订单明细_*.xlsx
#   大梦可能实验室（滨江店）_全渠道订单明细_*.xlsx
#   大梦_可能实验室_西湖店_菜品库_*.xlsx
#   大梦_可能实验室_滨江店_菜品库_*.xlsx
```

### 1. 在 V2 表追加 N 月空行 + 应用店色

确定 N 月起始行号（紧跟 N-1 月最后一行 + 1 空行分隔）。

```bash
# 例: 5 月起始 row 27（4 月结束 row 25, row 26 留空）

# 西湖 6 人 (rows 27-32) 浅绿
mcporter call tencent-docs sheet.set_cell_style --args \
  '{"file_id":"VLSAvSvqvYzU","sheet_id":"BB08J2","start_row":27,"end_row":32,"start_col":0,"end_col":42,"bg_color":"FFE2EFDA"}'

# 滨江 6 人 (rows 33-38) 浅蓝
mcporter call tencent-docs sheet.set_cell_style --args \
  '{"file_id":"VLSAvSvqvYzU","sheet_id":"BB08J2","start_row":33,"end_row":38,"start_col":0,"end_col":42,"bg_color":"FFDDEBF7"}'
```

### 2. 写入固定字段（每月不变）

为 12 名员工写入：月份、姓名、归属、部门、班次、岗位、兼任、状态、4 个标准（基本/KPI/管理/行为）。

可批量 set_range_value 一次发完。

### 3. 处理考勤资料

详见 `attendance_rules.md`。

针对 N 月：
- 读取所有图片用 Read tool 看清字
- 读取 xlsx 用 openpyxl
- 读取 xls 用 xlrd（首次需 `python3 -m pip install xlrd`）
- 读取腾讯文档夜班考勤（`file_id=IEqftKNqdqKa`）用 `get_content`

整理出每人的：出勤天数、加班小时数、备注（休息日期 + 年假说明 + 加班存/换钱）。

### 4. 写入考勤到 V2

set_range_value 写 cols 22 (出勤)、23 (法假)、24 (加班)、42 (备注)。

### 5. 写入营收数据

```bash
python3 ~/.claude/skills/dameng-salary/compute_cross.py "~/Downloads/大梦N月账务处理"
```

把脚本输出的 12 人 (部门业绩, 班次业绩, 部门×班次业绩) 写入 V2 cols 19/20/21。

记得应用特殊规则：
- 滨江厨房团队（刘/叶/尹）：班次 = 0，部门×班次 = 0
- 中班（尹志艳）：班次 = 0，部门×班次 = 0

### 6. 套用计薪公式

详见 `formulas.md`。对每个员工：

```python
basic = base * att / 26.08
ot_pay = 0 if banked else (oth / 9) * base / 26.08
kpi_res = kpi_std * 1.0    # 默认 1×
mgmt_res = mgmt_std * 1.0 if mgmt_std > 0 else 0
conduct_res = conduct_std   # 全额合格
commission = dept_rev * COMMISSION_RATE.get(name, 0)
holiday = base / 26.08 * lh_days * 2
total = basic + ot_pay + kpi_res + mgmt_res + conduct_res + commission + holiday
remaining = total - (523.53 if name in ENROLLED else 0)
```

写入 V2 cols 2 (汇总)、3 (剩余)、26-37 (各计算项)、39/40 (社保，仅 4 人)。

### 7. 生成工资单 HTML

```bash
# 首次本月运行：建立生成器目录
mkdir -p "~/Downloads/大梦N月账务处理/工资单生成器"
cp ~/.claude/skills/dameng-salary/fetch_salary.py "~/Downloads/大梦N月账务处理/工资单生成器/fetch_data.py"
cp ~/.claude/skills/dameng-salary/slip_template.html "~/Downloads/大梦N月账务处理/工资单生成器/salary_slips.html"

# 拉数据
cd "~/Downloads/大梦N月账务处理/工资单生成器" && python3 fetch_data.py 2026NN

# 打开
open "~/Downloads/大梦N月账务处理/工资单生成器/salary_slips.html"
```

### 8. 按需迭代

用户可能要求：
- 改某人考勤（重算工资）
- 调员工部门
- 改 KPI 倍数
- 改提成费率
- 加新员工

每次修改后重新跑公式 → 重新 fetch_data → 用户刷新页面。

### 9. 用户验收 + 导出 PNG

用户在页面右上角点 `EXPORT ALL` 批量导出，或单卡片 `DOWNLOAD PNG`。

---

## 已知坑点

### 行号偏移
腾讯文档 `set_range_value` 偶发 +1 行偏移。**写完务必读回校验**。

之前发生过：4 月写入时尹志艳被宋群喜覆盖。修复办法：append 到末尾再重排顺序。

### 出勤口径
"出勤天数"的口径：
- xlsx 文件用「实际出勤天数」= 当月到岗天数（不含调休/年假）
- 夜班手写考勤的「出勤」列：含年假，约等于 30 - 真休
- 用户最终口径（5 月起请遵循）：**出勤 = 实际工作天数 + 年假天数（按工作日计薪）**
- **若不确定，问用户**

### 加班 "存 vs 换钱"
- 备注里看清楚
- "存"则 加班工资 = 0
- "换钱"或无注则正常发

### 朱秋风部门变动
4 月起 朱秋风 从「前厅」改到「精酿」部门，但岗位仍是「前厅运营」。新月份继承。

### 节假日补贴 vs 法定假期换薪
- V2 有两列：法定假期换薪 (col 34) 和 节假日出勤补贴 (col 36)
- **只用 col 36**，col 34 保持 0
- 工资单 HTML 现在只读 col 36

### 滨江店是否有提成
3 月全员 0，4 月仍 0。**何时开始有，由用户决定**。

### "保洁阿姨" 不写入 V2
她是兼职，5 月起若仍出现在考勤图片，只采集数据不写表。

---

## 营收分析引擎（5月新增 build_analysis.py）

当月若**没有**预生成的「N月营收分析xlsx」，用 skill 自带引擎从原始订单直接生成：

```bash
python3 ~/.claude/skills/dameng-salary/build_analysis.py "~/Downloads/大梦N月账务处理" 2026-NN
```

产出：`大梦可能实验室_N月营收分析_西湖店vs滨江店.xlsx`(13 sheets) + `_analysis_summary.json`(供工资写表)。
summary.json 里 `employees` 即 12 人 (部门业绩/班次业绩/部门×班次业绩) 三元组，直接写 V2 cols 19/20/21。
引擎已内置：菜品归口、团购→部门拆分、代金券剔除、部门×班次比例校正、滨江厨房/中班置0。

**强烈建议**：跑完用 workflow 做 5 路独立复核（部门POS/班次/团购/交叉/环比）——5 月就靠它抓出 2 个真 bug。

数据治理坑点（引擎已修，每月仍需注意）：
- 🔴 **幽灵汇总行**：POS「订单明细」末尾 `订单来源/订单号/营业日期 全='--'` 行，金额=全部真实行之和→订单级字段翻倍2x。必须 `if str(订单号).strip()=='--': continue`。
- 🔴 **dish级 vs 订单级**：部门收入用「菜品明细」逐菜累加；订单级列被联台重复，勿用。
- 🟡 **酒头/畅饮票=精酿**（非调酒）。
- **分类名会变**：西湖 4月`brunch`→5月`brunch轻食简餐`，用 `startswith` 容错。
- **新团购套餐每月扫一遍**（5月新增「咖啡任选7次卡」→咖啡）。
- **约6%营收是"无菜品库"SKU** 靠关键词兜底，错归风险源。
详见 `analysis_playbook.md`。

---

## 5 月跑通经验（已回填 · v1.1，覆盖更早的草稿口径）

**行号**：5月 = rows 27-39（13人，西湖27-33/滨江34-39），row 26 空行分隔。6月起始 = row 41。

**人员变动**：
- 新增 **舒尧轩（昵称小胖）**，西湖调酒晚班/调酒师，底薪5600/KPI1000/行为500/管理0；无社保、暂无提成。
- 现 **13 人**（西湖7+滨江6）。重排规则：西湖在前、滨江在后；舒尧轩紧跟胡舒（同调酒晚班）。

**出勤口径（用户确认，覆盖4月）**：
- **年假计入出勤**（带薪）。出勤 = 当月天数 − 正常休息(不含年假)。各考勤表写明的出勤数为准。
- 何简28(3天年假计入)、郭思儒27、秦天29、胡舒27、舒尧轩27 等。

**法定假期（用户确认）**：五一 **2 天**，**全员**法定假期天数=2、全给双倍 → 节假补贴 = 底薪/26.08 × 4。

**加班**：胡舒4h存、舒尧轩1.5h存 → 不发；其余"换钱"或未注明照发。蔡逸丰"3+9换钱(五一白班)"=12h换钱。

**工资单两条新展示规则**（slip_template.html 已内置，自动生效）：
- 未交社保者基本工资下注明"已含社保 ¥1,745.78"。
- 出品提成行仅对有提成者显示，其余隐藏。

**考勤来源（5月实例）**：厨师考勤表.jpg(秦天/刘润祥/叶磊/尹志艳/何简)、小王考勤表.jpg(王瑛胤)、西湖店白班考勤表.jpg(宋群喜/郭思儒/保洁)、李想5月.xlsx、秋风5月.xlsx、腾讯夜班文档(胡舒/蔡逸丰/小胖=舒尧轩)。

**5月节假日**：五一2天（不是1天）。

**营收/出品分析**：本月新增完整分析能力，详见 `analysis_playbook.md`。5月双店POS四部门合计 西湖229,059/滨江156,326(+6.6%/+8.0%)。