# RULES · 共同规范

> 竹间架构 R层："一条规则只有一个家"。Pipeline 脚本引用，禁止再散落在 memory/skills 里。
> 每条规则标注适用场景，拿到文件知道查哪条。

---

## R1 · ERP 数据管线

### R1.1 合计行过滤
> 适用：任何 ERP Excel 处理脚本

ERP 导出 Excel 的末尾通常有合计行（金额汇总），必须过滤，否则数据虚增。

```python
# 检测：客户列为空 或 单据编号为空
if not cust or not order_id: continue
```

### R1.2 月份检测 = ZHBR 前缀
> 适用：需要从订单提取月份的任何场景

ERP 单据编号格式 `ZHBR{YYMM}{seq}`，月份 = 编号第 5-6 位。

```python
month = order_id[4:6]  # '01'-'12'
```

### R1.3 测试单提取
> 适用：需要剔除或单独统计测试单的场景

```python
df[df['单据类型'].str.contains('测试')]
# 按单据编号 nunique 去重（一单多行拆行）
```

### R1.4 宝锐系剔除
> 适用：所有销售业绩统计

```python
internal = {'珠海宝锐生物科技', '珠海横琴宝锐生物科技', '珠海宝泰仪生物科技'}
if cust in internal: continue
```

### R1.5 openpyxl 读取
> 适用：任何用 openpyxl 读 Excel 的场景

- 必须用 `values_only=True`
- `wb['Sheet1']`，不能用 `wb.active`（active 可能是空 Sheet）
- 2025/2026 文件日期列是字符串 `"YYYY-MM"`，不是 datetime

### R1.6 列索引映射
> 适用：写新的 ERP 处理脚本前必须查这张表

| 文件 | 客户 | 日期 | 销售员 | 价税合计 | 单据类型 | 赠品 | 产品大类 |
|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| 主ERP(2026) | 0 | 1 | 2 | 3 | 5 | 13 | 24 |
| 2024全年 | 4 | 0 | 5 | 12 | 2 | 14 | 26 |
| 2025全年 | 3 | 0 | 5 | 12 | 1 | 14 | 26 |
| 2026年1-6月 | 4 | 0 | 6 | 13 | 1 | 15 | 25 |
| ERP16K | 3 | 0 | 4 | 11 | 2 | 14 | 26 |

### R1.7 数据源优先级
> 适用：数据冲突时判断以谁为准

```
ERP > 月度报告Excel > MCP > 推算
```

---

## R2 · KPI 计算

### R2.1 金额唯一可靠源 = ERP
> 适用：任何涉及金额计算的场景

严禁从 MCP 拉金额或按比例分摊。MCP 金额大量为 0（测试单/预测单）。

### R2.2 代号映射
> 适用：2025 年及更早的 ERP 数据

- 大客户1 → 黄明月
- 大客户2 → 赵云浩  
- 王昕伟 → 赵云浩（合并）

### R2.3 年化达成率
> 适用：看板卡片、KPI 报表

```
pct = (累计实际 / 已过月份数 × 12) / 年度目标 × 100
```

---

## R3 · CloudBase 部署

### R3.1 部署命令
> 适用：任何需要部署到 CloudBase 的场景

```bash
tcb hosting deploy 工具/index.html /workbench/index.html -e bier-sales-d0gatbvlx288724e9
```

### R3.2 CDN 缓存
> 适用：部署后页面没更新

- CDN 缓存 2-5 分钟
- 验证用 `curl -H "Cache-Control: no-cache"` 或无痕模式

### R3.3 cb_sync_data.sh 只同步 JSON
> 适用：改了 HTML 但没生效

HTML 文件需单独 `tcb hosting deploy`，改了 HTML 必须手动部署。

---

## R4 · 角色分权

> 适用：新增用户或权限问题时查

| 角色 | 可见范围 |
|------|---------|
| admin / gm | 全部数据 |
| manager | 本部门 + 管辖区域 |
| sales | 本人数据 |

---

## R5 · 页面规范

### R5.1 零依赖
> 适用：新建或改造任何 HTML 页面

- 所有 HTML 自包含
- Chart.js 本地化（`/工具/chart.umd.min.js`）
- 不引用外部 CDN

### R5.2 命名
> 适用：新建文件

- 页面：中文名，不超过 15 字
- 数据文件：英文小写 + 下划线

### R5.3 配色
> 适用：任何涉及颜色的页面

- 主色：宝锐蓝 `#1a73e8`
- 2024=灰 `#9e9e9e`，2025=金 `#f4a236`，2026=蓝 `#1a73e8`