# semiconductor-agent

**Repository Path**: simon1239/semiconductor-agent

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 半导体财务数据底座 + 全年毛利最优化

> 一个可复现的存储 IDM 财务模拟库（41 表 / 72,235 行），
> 以及建立在其上的**销量调整最优化引擎**（LP，1,920 变量 / 0.35 秒求解 / 7 道验收闸门）。

对标对象：**三星 / 海力士 / 美光**的存储 IDM 业务（DRAM / NAND / HBM，重资产折旧结构）
＋ **英伟达**的 AI 芯片高毛利业务。用途是问数、归因、最优化求解的开发与验证，
**全部数据为模拟生成，非真实企业数据**。

> **接手本项目先读**：[`客户结构扩容_任务交接.md`](./客户结构扩容_任务交接.md)
> （含当前基线口径、编辑纪律、已知坑与待决策项；对账伴随件 `客户结构扩容_对账.json`）。

---

## 30 秒上手

```bash
git clone https://gitee.com/simon1239/semiconductor-agent.git
cd semiconductor-agent
PY=python                      # 需要 numpy / scipy / PyYAML

# 1) 看最优解（毛利 2,643,002.2 万元 / 销量 497,772.9 千颗）
$PY scripts/group_coupled_optimizer.py

# 2) 过七道验收闸门（退出码 0 才算可用）
$PY scripts/verify_demand_grain.py --strict

# 3) 导出调整前/后 8 张销量表到 reports/
$PY scripts/export_adjusted_sales_plan.py
```

跑完第 1、2 步的预期输出见 **[附录：回归基准](#附录回归基准)**。
换机器/换环境后先跑第 2 步，闸门全绿再谈结果。

> 完整操作规范（谁做、怎么做、出错怎么办）见
> **[`docs/操作SOP_销量调整最优化_v1.md`](docs/操作SOP_销量调整最优化_v1.md)**。

---

## 两条主线

```
      ┌─────────────────────────────────────────────────┐
      │  主线一：数据底座                                 │
      │  41 表 / 44,422 行 / 6 家实体的三表 + 制造 + 行业  │
      └───────────────────────┬─────────────────────────┘
                              │ 供给、需求、成本、产能、库存
      ┌───────────────────────▼─────────────────────────┐
      │  主线二：全年毛利最优化                            │
      │  需求 (i,s,c) ──桥接──> 决策 (p,c) ──LP──> 销量表  │
      └─────────────────────────────────────────────────┘
```

**主线一**回答"公司现在什么状况"（`question_agent` / `attribution` / `metric_catalog`）。
**主线二**回答"货怎么配最赚钱"（`group_coupled_optimizer` 及其分析脚本）。

两条线共用同一个 `semiconductor_finance.db`，口径由 `config/*.yaml` 单一来源定义。

---

## 一、数据底座

### 1.1 规模

| 项 | 值 |
|---|---|
| 数据库 | `semiconductor_finance.db`（SQLite 3，含外键/约束/索引/视图） |
| 表 | **41 张**，合计 **44,422 行** |
| 历史数据 | 2021-01 ~ 2026-06（**66 个月**，actual） |
| 预测数据 | 2026-07 ~ 2028-06（forecast） |
| 产品 | **14 个**（DRAM 3 + 移动 DRAM 2 / NAND 3 / HBM 2 / eSSD 2 / AI 芯片 2） |
| 客商 | **16 个**（PC / 手机 / 服务器 / 云厂商 / 汽车 / 分销） |
| 实体 | 4 家（含合并抵消 `consolidation_elimination`） |
| 金额单位 | 万元（单价、单位成本为元/颗） |
| 产量单位 | 千颗 / 月 |

### 1.2 表分组

| 组 | 表（行数） |
|---|---|
| **财务三表** | `entity_statements`(8,820) `fab_statements`(13,770) `forecast_statements`(1,980) `consolidation_elimination`(90) `inter_entity_transactions`(180) |
| **经营事实** | `sales_facts`(6,207) `sales_plan_facts`(**3,168**, 计划) `cost_facts`(664) `production_facts`(664) `inventory_facts`(664) `process_yield_facts`(664) `cycle_time_facts`(664) `wafer_manufacturing_facts`(664) `capex_facts`(66) `hbm_stack_facts`(156) |
| **产线与排产** | `production_schedule_plan`(378) `chamber_schedule_facts`(216) `equipment_dim`(7) `chamber_dim`(18) `packaging_platform_dim`(10) |
| **行业与需求** | `industry_supply_demand`(43) `industry_cycle_facts`(336) `idm_demand_supply`(**31,524**) `market_supply_plan`(6) |
| **维度** | `product_dim` `product_spec_dim` `product_master` `customer_dim`(**68 家**) `region_dim` `market_dim` `entity_dim` `fab_dim` `vendor_dim` `global_company_dim` `process_node_dim` `technology_era_dim` |
| **治理** | `rule_registry`(**88 条**) `rule_param`(**108 参数**) `data_dictionary`(312) `fab_kpi_facts`(157) `vendor_kpi_facts`(450) |

> **客户结构（假设 A19）**：68 家客户（C01~C68），每个 segment 15 家：
> 数据中心 15 / 数据中心边缘 15 / 汽车工业 15 / 消费电子 15 / 移动通信 15。
> 客户归属 segment = 其采购产品 segment 的并集，故 68 家对应 75 个段位归属；
> 每产品覆盖 7~15 家客户。客户名为真实下游企业，**采购关系与份额为模拟分摊**（A2/A19），
> 不得作为真实客户份额依据。销量按客户池权重归一化分摊 → 扩池不改变产品级销量与收入总量。

> `idm_demand_supply` 是唯一的**分月 × 公司 × 客户**粒度供需表（2021-01~2028-06 / 90 月 / 4 家 / 31,524 行）。
> 全表统一 `千颗`（外资=赛道指数 × 全球基数/1200，假设 A18 mock 定标，只定相对量级）；
> 外资客户维度是 mock 分摊（假设 A2），详见 `docs/供需拆分规则_v1.md`。
>
> **需求 ≠ 销量，两者无勾稽义务**：`idm_demand_supply.demand_qty_k` 是机构口径预测数，
> `sales_facts.sales_volume_k` 是产能-库存-订单派生的综合预测值——两条独立预测链，
> 不要求相等（`gap` 为负＝卖超预期），也不得为了"对齐"而改需求。只有 `supply` 与
> `sales_facts` 做逐月勾稽（F12，0 偏差）。

**`sales_facts` 的产品属性列由维表自动推导**（`gen_all_data.product_attrs()`，禁手工维护）：

| 列 | 推导源 | 示例 |
|---|---|---|
| `product_density` | `product_spec_dim.capacity_gb`，**统一 GB 口径**（颗粒按 1B=8bit 换算，SSD 十进制） | P01→`1GB`、P07→`3840GB` |
| `pn` 料号 | `DX-{接口族}-{密度码}-{位宽码}-{等级码}`，四个属性任一变化即变号 | P01→`DX-DR4-08G-X8-C` |
| `speed` | `product_dim.speed_mts`（颗粒）/ `bandwidth_gbps`（整机、AI） | P08→`8.2 TB/s` |
| `package_type` | `product_spec_dim.package_type`（单一来源） | P04→`Interposer+CoWoS-S` |
| `ic_config` | **严格只取 die IO 位宽 x8/x16**；x32/HBM 总位宽/PCIe 通道属其他语义层，留空 | P01→`x8`、P11→`（空）` |

> **`product_type` 已于 2026-10-26 拆分为两个维度**：`product_family` 存业务大类
> （DRAM/DRAM Mobile/NAND/HBM/Enterprise SSD/AI Chip，行业周期表主键与线级优化按它聚合），
> `product_type` 存产品形态（IC 8 个 / Module 6 个 / Wafer 当前无此类销售 SKU）。
> 迁移脚本 `scripts/migrate_product_semantics.py` 排在重建链第 10 步，幂等可重复。

### 1.3 业务周期（实测，非设定值）

| 年份 | 营业收入 | 净利率 | 阶段 |
|---|---:|---:|---|
| 2021 | 54.97 亿 | 8.31% | 成长期，产能爬坡 |
| 2022 | 84.80 亿 | 1.73% | 价格下行开始 |
| **2023** | **136.93 亿** | **−2.69%** | **冰河期：量价齐跌，出现亏损** |
| 2024 | 326.33 亿 | 11.95% | HBM3E 上市，AI 需求启动 |
| 2025 | 440.03 亿 | 20.85% | 存储涨价 + AI 放量 |
| 2026（H1） | 235.97 亿 | 25.43% | AI 爆发，产能满载 |

> 2026 只有 H1 是 actual；H2 在 `forecast_statements` 里（全年约 480 亿）。
> 查询口径：`entity_statements` 中 `statement='income_statement'` + `scope='consolidated'`。

### 1.4 数据治理

```bash
$PY scripts/audit_data_governance.py
```

当前状态：**P0 = 0**；10 项 P2 已裁定豁免（`GOV-001`~`GOV-010`：两位小数舍入、同名字段不同口径等）。
裁定结论与复核期固化在 `docs/数据治理手册_v1.md`；体检明细是跑批产物
（`reports/数据治理体检_<日期>.md`，已被 gitignore，跑一次即重建）。

规则登记与漂移检查：

```bash
$PY scripts/sync_rule_registry.py                # 同步 config → rule_registry
$PY scripts/sync_rule_registry.py --check        # 必须输出「无漂移」才能提交（含假设引用校验）
$PY scripts/sync_rule_registry.py --check-refs   # 只查「假设 A<n>」引用是否有定义
```

`--check` 除指纹漂移外，还扫描全仓「假设 A<n>」引用：**引用了未定义的编号即判失败**。
（历史坑：`semantic_layer.yaml` 曾引用从未定义的 A17，实为 A7 的内容；A6/A7 也曾撞号。
新增假设前先跑 `--check-refs` 确认编号未被占用。）

7 个配置文件是规则的**唯一来源**：
`idm_allocation.yaml`（供需拆分 R1~R6 + A1~A5、A18、A19）/ `market_demand.yaml`（需求侧 15 条 + A8~A10、A13~A16）/
`yield_policy.yaml`（良率政策 + A11/A12）/ `market_coupling.yaml` / `production_schedule.yaml`（+ A6/A7）/
`data_governance.yaml` / `indicator_system.yaml`。
假设编号 A1~A19 中 **A17 为空号**（从未定义，曾被 A7 的内容误引用，2026-10-22 修正为 A7）。

---

## 二、销量调整最优化（核心）

### 2.1 要解决的问题：四层口径错位

需求表是 `interface × segment × customer`，销量表是 `product × customer`。两者对不上：

| 层 | 错位 | 后果 |
|---|---|---|
| L1 单位 | ~~GC00 千颗 vs 外资指数~~ **已修复**（2026-10-22 统一千颗，假设 A18） | 量纲混用 |
| L2 客户维度 | `D(i,s,c)` 是按实际销量等比分摊的，**零信息** | 客户维度只能当价格维度用 |
| L3 粒度 | 需求表没有 `product` | 产品结构无法决策 |
| L4 水平 | 80 格外推需求 < 实际销量 | 会逼客户"退货" |

**根因不是数据对不上，而是约束写在了错的粒度上。**

### 2.2 解法：约束留在原生粒度，结构交还优化器

```
Σ_{p∈g} q(p,c,t)  ≤  D(i,s,c,t)        ← 上界留在「组×客户」
```

上界不写在产品上，产品结构才成为决策自由度。桥接 `3 种需求粒度 × 2 种客户维度 = 6 组合`，
其中 4 组合有效：

| `demand_mode` | `cust_dim` | 毛利(万元) | 判定 |
|---|---|---:|---|
| `product` | False | 2,597,754.8 | ✅ 旧硬拆，锁死结构 |
| `group` | False | 2,599,049.7 | ✅ 无客户维反而更低，符合预期 |
| `group` | True | 2,725,633.7 | ✅ 仅理论上界（突破客户需求上限，不可执行） |
| **`cell`** | **True** | **2,643,002.2** | ✅ **推荐生产口径** |

> 另外 2 组合（`product/True`、`cell/False`）会**退化成零需求约束**，
> 解是"无上界"的假解，不计入可行口径。

三个干净的价差：

- `cell − product = +45,247.4 万元（+1.742%）` —— 切粒度总收益
- `group带客户 − group无客户 = +126,584.0 万元（+4.870%）` —— **客户维度的真实价值**（不在需求信息，而在「有权利选择卖给谁」）
- `cell − group带客户 = −82,631.5 万元` —— 遵守客户需求上限的代价

> **2026-10-22 客户结构扩容重定基**：鼎芯客户池由 16 家扩到 68 家（每 segment 15 家，假设 A19），
> 销量总量不变（497,772.9 千颗），但客户粒度变细使全部情景毛利重定基：
> 推荐口径 D 由 `2,652,551.5` → **`2,643,002.2` 万元（−0.36%）**，变量 864 → 1,920。
> 本节以下深度分析（杠杆弹性、影子价、单点开关等）仍是**扩容前快照**，
> 引用前需重跑 `analyze_multi_period.py` / `analyze_combined_scenario.py` 刷新。

### 2.3 关键结论

| # | 结论 | 数字 |
|---|---|---|
| 1 | **瓶颈是产能，不是需求** | 产能杠杆 0.716 vs 需求杠杆 0.142（**差 5.0 倍**） |
| 2 | 需求 +10% 几乎不增量 | 毛利 +1.42%，销量仅 **+148.5 千颗（+0.03%）** |
| 3 | 增益来自"同量换结构" | 销量 497,772.9 → 497,772.9（**Δ=0**），毛利 **+1.87 亿** |
| 4 | 结构要按毛利密度排 | P08 密度 7,083.7 万元/千颗，是 P05 的 3.5 万倍 |
| 5 | 需求侧只剩一个客户值得争 | HBM3E/数据中心/微软Azure 占正影子价的 98.2% |
| 6 | 良率是最便宜的单点开关 | P08 良率 **+1pp = 494.8 万元**（有限差分验证） |
| 7 | 看似严重的组间错配主要是假设镜像 | 剥离 A3/A4 假设后真实松紧差异仅 **8.0%** |

### 2.4 模型规模

| 项 | 值 |
|---|---:|
| 变量 | 864 = q 528 + y 168 + v 168 |
| 约束 | 1,157 = 等式 168 + 不等式 989 |
| 不等式构成 | `DEM_CELL` 420 / `YIELD_HI` 168 / `YIELD_LO` 168 / `EPS` 180 / `RETAIN` 44 / `INV_FLOOR` 9 |
| 求解 | `scipy.optimize.linprog(method="highs")`，**0.13 秒** |

### 2.5 七道验收闸门

```bash
$PY scripts/verify_demand_grain.py --strict   # 任一告警即 FAIL，退出码 0/1
```

| 闸门 | 守什么 |
|---|---|
| G1 | 组级需求不超限 `Σ_{p∈g} q ≤ max(D, 实际)` |
| G2 | 采购关系合规（不许卖给没买过的客户） |
| G3 | 结构弹性合规 `\|s − s0\| ≤ ε` |
| G4 | 历史兜底生效（不许让客户退货） |
| G5 | 明细自洽（`detail` = `by_p` = `by_c` = 目标值） |
| G6 | 客户线保留（不许把客户砍掉） |
| G7 | 库存政策自洽（`inv_floor` 未被隐式改掉） |

### 2.6 八个输出表

`scripts/export_adjusted_sales_plan.py` → `reports/`

| 层级 | 文件 | 行数 |
|---|---|---:|
| 调整前 | `调整前销量表_{客户级,产品级,月度汇总}.csv` | 491 / 168 / 12 |
| 调整后 | `调整后销量表_{客户级,产品级,月度汇总}.csv` | 528 / 168 / 12 |
| 对照（产品×客户） | `调整前后对照_客户级.csv` | 528 |
| **对照（市场单元 `(i,s,c)`）** | `调整前后对照_市场单元.csv` | **420** |

最后一张是需求侧的原生粒度，420 = 35 个 `(i,s,c)` × 12 月，与 `DEM_CELL` 约束逐条对应。

---

## 三、文档地图

**入口三份**（按顺序读）：

| 文档 | 作用 |
|---|---|
| **[操作SOP_销量调整最优化_v1](docs/操作SOP_销量调整最优化_v1.md)** | 怎么跑、怎么验收、出错怎么办（**先看这份**） |
| **[销量调整算法说明书_v1](docs/销量调整算法说明书_v1.md)** | 输入/输出/目标函数/7 组约束/Step0~11/参数速查 |
| **[讨论纪要_2026-10-21](docs/讨论纪要_2026-10-21.md)** | 13 轮讨论的索引与决策台账 |

**数据底座**：

| 文档 | 作用 |
|---|---|
| **[数据表说明_v1](docs/数据表说明_v1.md)** | 41 表 + 10 视图，**逐表字段表格**（453 字段：类型/说明/取值样例）/ 颗粒度 / 时间覆盖 / 六条禁忌 |
| [颗粒度防护视图_v1](docs/颗粒度防护视图_v1.md) | 四个颗粒度陷阱的成因、错误后果与安全视图用法 |
| [多期毛利优化_问题1问题2_建模与求解_v1](docs/多期毛利优化_问题1问题2_建模与求解_v1.md) | 两个优化问题的 LP 建模、多期解法、帕累托前沿与约束可行性诊断 |

**问题与方案**：

| 文档 | 内容 |
|---|---|
| [需求口径错位处理_v1](docs/需求口径错位处理_v1.md) | 四层错位实测与约束改造（诊断） |
| [需求口径错位解决方案_v1](docs/需求口径错位解决方案_v1.md) | 方案书：三动作、场景阶梯、四项发现 |
| [数据流转与供需错配_v1](docs/数据流转与供需错配_v1.md) | R5/R6 拆分、客户维零信息证明、五层错配诊断、桥接 2×2 |
| [市场预测驱动销售优化_可行性验证](docs/市场预测驱动销售优化_可行性验证.md) | 市场预测接入的可行性与清库存陷阱 |

**分析与结论**：

| 文档 | 内容 |
|---|---|
| [销量调整最优化分析报告_v1](docs/销量调整最优化分析报告_v1.md) | 约束画像、影子价格、灵敏度、毛利密度 |
| [多期最优分析报告_v1](docs/多期最优分析报告_v1.md) | 折现、残值陷阱、承诺窗、组合情景全因子 |
| [良率成本与客户维度_v1](docs/良率成本与客户维度_v1.md) | 客户维度价值、良率成本模型、口径补正 |
| [鼎芯全年毛利最大化最优化求解调研](docs/鼎芯全年毛利最大化最优化求解调研.md) | 求解方法论调研 |

**口径与治理**：

| 文档 | 内容 |
|---|---|
| [供需拆分规则_v1](docs/供需拆分规则_v1.md) | 供需表口径与 R5 拆分规则 |
| [数据生成规则_市场耦合_v1](docs/数据生成规则_市场耦合_v1.md) | 全球市场线 × 自有企业线耦合 |
| [排产计划规则_v1](docs/排产计划规则_v1.md) | 内部排产表与腔室当量口径 |
| [数据治理手册_v1](docs/数据治理手册_v1.md) | 治理阈值、体检项、修复流程 |
| [数据驱动指标体系落地规划方案](docs/数据驱动指标体系落地规划方案.md) | 指标体系规划 |
| [PRD](docs/PRD.md) | Agent 平台产品需求文档 |

**调研底稿**（`docs/research/`，9 份）：半导体制造工艺与技术时代六视角调研 + 三星 / 海力士 / 美光 /
台积电 / 英特尔工程师批注版，是数据底座里工艺、技术时代、厂商知识边的来源材料。

---

## 四、目录结构

```
semiconductor-agent/
├── semiconductor_finance.db      # 唯一数据源（41 表 / 44,422 行）
├── config/                       # 7 个 YAML = 规则的唯一来源
│   ├── idm_allocation.yaml       #   供需拆分 R1~R6 + A1~A5
│   ├── market_demand.yaml        #   需求侧 15 条规则 / 14 参数 / A8~A16
│   ├── yield_policy.yaml         #   良率政策
│   ├── market_coupling.yaml      #   市场线 × 自有线耦合
│   ├── production_schedule.yaml  #   排产与容量口径
│   ├── data_governance.yaml      #   治理阈值
│   └── indicator_system.yaml     #   指标体系
├── docs/                         # 17 份主文档 + research/ 9 份调研底稿
├── scripts/                      # 33 个脚本
│   ├── group_coupled_optimizer.py    # ★ LP 求解器（核心）
│   ├── verify_demand_grain.py        # ★ 七道闸门
│   ├── export_adjusted_sales_plan.py # ★ 8 张销量表
│   ├── market_demand.py              #   需求加载器
│   ├── trace_data_flow.py            #   数据流转追踪
│   ├── analyze_sales_adjustment.py   #   影子价/灵敏度
│   ├── analyze_multi_period.py       #   折现/残值/承诺窗
│   ├── analyze_combined_scenario.py  #   组合情景全因子
│   ├── scan_inventory_policy.py      #   库存政策扫描
│   ├── yield_cost_sensitivity.py     #   良率成本敏感性
│   ├── audit_data_governance.py      #   数据体检
│   ├── sync_rule_registry.py         #   规则登记与漂移
│   ├── rebuild_all.py               #   一键全量重建（固定 10 步顺序）
│   ├── create_guard_views.py        #   颗粒度防护视图（4 个陷阱的安全口径 + 断言）
│   ├── gen_table_doc.py             #   由库结构生成《数据表说明》的逐表字段表格
│   ├── export_sales_with_yield.py   #   导出销售数据（asp / nduc+depr / cum+五段良率，英文表头）Excel
│   ├── analyze_multiperiod_lp.py    #   复算问题1/问题2 的 LP 结果与帕累托前沿
│   ├── register_dictionary.py        #   非核心表字段口径登记（130 条）
│   ├── build_*.py / gen_*.py         #   数据生成与重建
│   └── ...                           #   报表与工具
├── 根目录 17 个 .py               # Agent 平台层（见 4.1）
├── tests/                        # 9 个用例 / 76 个子测试
├── .github/workflows/ci.yml      # CI：pytest
└── reports/                      # 跑批产物（gitignore，可随时重建）
```

### 4.1 Agent 平台层（根目录）

| 模块 | 职责 |
|---|---|
| `question_agent.py` | Phase 1 问数 Agent（自然语言 → SQL） |
| `attribution.py` | Phase 2 归因流水线 |
| `optimizer.py` / `milp_optimizer.py` | Phase 3 最优化（产品组合 / 多期 MILP） |
| `yearly_margin_optimizer.py` | 全年毛利最大化求解器（底层毛利/产能/库存模型） |
| `expert_engine.py` / `skill_loader.py` | Phase 4 专家系统 + 技能库 |
| `agent_framework.py` / `agent_platform_v2.py` | 统一框架与七大能力入口 |
| `metric_catalog.py` / `metric_governance.py` | 指标目录与治理 |
| `preregistration.py` / `drift_monitor.py` | 预注册对抗审查 / 漂移监控 |
| `semantic.py` | 语义层管理 CLI |
| `paths.py` | 统一配置/路径层（single source of truth） |

三层防线（防 LLM 幻觉）：语义层约束生成 → 数值自校验（勾稽）→ 预注册对抗审查。

---

## 五、运行与验收

### 5.1 环境

| 项 | 值 |
|---|---|
| Python | 3.13.x（本机实测 3.13.5；CI 用 3.11） |
| 依赖（`requirements.txt` 锁定） | `numpy==2.4.6` `PyYAML==6.0.3` `scipy==1.17.1` |
| **本机实测通过（附录基准即此环境）** | numpy **2.5.1** / scipy **1.15.3** / PyYAML **6.0.2** |

> ⚠️ **锁定的 scipy 版本与本机实测版本不一致**（`requirements.txt` 写 1.17.1，实测 1.15.3）。
> LP 求解路径可能随 scipy 版本变化，进而导致数值抖动。
> **按 `requirements.txt` 装完环境后，必须先跑 `verify_demand_grain.py --strict`
> 并与附录基准逐项对照，全绿才能用。** 若对不上，回到 scipy 1.15.3 复现。

> 有一串 `from scipy.optimize import milp ...` 的版本告警，**是正常的**，不影响结果。
> 不要为了消警去升降包——换版本可能改变 LP 求解路径。

### 5.2 标准跑批

```bash
PY=python

$PY scripts/audit_data_governance.py          # S1 数据体检（应有 P0=0）
$PY scripts/group_coupled_optimizer.py --csv  # S2 全情景对比（A/A2/A'/B0/B1/B1h/C×4/D）
$PY scripts/verify_demand_grain.py --strict   # S3 七道闸门（必须 exit 0）
$PY scripts/export_adjusted_sales_plan.py     # S4 导出 8 张表
$PY scripts/sync_rule_registry.py --check     # 提交前：无漂移 + 假设引用完整
```

必做流程约 8 秒；加 5 个分析脚本约 23 秒。

### 5.3 测试

```bash
$PY -m pytest tests/ -q      # 9 passed, 70 subtests
```

CI（`.github/workflows/ci.yml`）在 Windows + Python 3.11 上跑同一套测试。

### 5.4 参数覆盖入口

| 想改什么 | 用哪个 |
|---|---|
| 跑标准八情景 | `group_coupled_optimizer.py --csv`（**只支持 --csv**） |
| 改参数并过闸门 | `verify_demand_grain.py --eps 0.02 --retain 0.9 --inv-floor 0.78 --capacity-mode actual` |
| 改参数并导表 | `export_adjusted_sales_plan.py --eps ... --retain-scope ... --baseline legacy` |

> ⚠️ `group_coupled_optimizer.py` 传未知 `--flag` 会**报错退出（码 2）**，
> 不会静默按默认值跑——这是刻意设计，避免拿着错误参数结论去汇报。

---

## 附录：回归基准

**换环境后先对这张表；对不上不许交付。**

| 项 | 值 |
|---|---|
| 三情景毛利(万元) | A 2,597,754.8 ｜ A′ 2,611,909.5 ｜ **D 2,643,002.2** |
| 销量(千颗) | 496,235.6 ｜ 497,772.9 ｜ **497,772.9** |
| 变量 / 约束 | 1,920 / 2,145 |
| `detail` 行数 | 1,214 |
| 校验技巧 | `len(sol["duals"]) == sol["n_ub"]` 必须为 True |
| 闸门 | 7 PASS，exit 0；G4 兜底 262 格；G7 期末/期初 100.27% |
| 规则库 | 88 条 / 108 参数 |
| `sync_rule_registry --check` | 无漂移；假设引用完整（18 条定义，A17 空号） |

`D − A = +45,247.4 万元（+1.742%）` = 兜底 +14,154.7 + 粒度 +31,092.7
`D − A′ = +31,092.7 万元（+1.190%）`，销量完全相同

> 以上为 2026-10-22 客户结构扩容（16 → 68 家 / 每段 15 家，假设 A19）后的**重定基口径**。
> 扩容前基准为 D `2,652,551.5` / 864 变量 / 418 明细行，差异来自客户粒度变细（销量不变，毛利 −0.36%）。

---

## 六、已知局限（引用结论必须一并说明）

| # | 局限 | 影响 | 状态 |
|---|---|---|---|
| 1 | **需求是 R5 外推 + 假设，不是订单**（A3 HBM +44.2% 为推导值、A4 NAND 0% 为纯假设、A8） | 结论是**情景最优**，不是预测 | 已登记 |
| 2 | 客户 ASP 用 `sales_facts` 加权，未区分价格歧视与规格差异（A14） | 结构收益可能高估 | 需客户合同价格表 |
| 3 | 良率上界未计价（`YLD_UNCOST`） | 7 个低良率产品白得 717.6 千颗（0.14%）；2.3 节的 494.8 万元是**毛收益** | 已登记未修 |
| 4 | `inv_floor=1.0` 未获业务确认（A15） | 影响 ±0.43%（1.14 亿） | **待业务决策** |
| 5 | `capacity_mode=flat` 把历史月产能高估 0.30% | 绝对水平偏高 0.86% | 可切 `actual` |
| 6 | 未接入产能扩张投资成本 | "每 +1% 产能值 1.95 亿"是收益侧，非净现 | 未做 |
| 7 | 未做价格弹性 | 假设 ASP 外生，降价提量会改变结论 | 未做 |

**四个"产能"口径别混**（这是最容易出错的地方）：

| 口径 | 数值（千颗） | 含义 |
|---|---:|---|
| 投片容量 | 281,630.0 | 物理机台上限 |
| 实际投片 | 258,949.3 | 利用率 91.9%，**可回收** |
| 实际产出 | 246,279.1 | 良率 95.11% |
| 打满后产出上界 | 267,850.0 | 仍缺 9,530.8（3.44%）→ **只有这部分真需要扩产** |

---

## 七、版本

| 标签 | 提交 | 内容 |
|---|---|---|
| `v1.0` | `4851762` | 七能力 Agent 平台 + 六视角制造模型 + 数据库 |
| **`v1.0.1`** | **`39a1d73`** | **销量调整最优化全链落地（LP 求解器 + 8 张销量表 + 操作 SOP）** |

分支：`master`（主）｜`feature-v1.0.1`（已合并，保留）

---

## 许可与声明

本项目为**模拟数据与算法验证**用途，`semiconductor_finance.db` 中的企业、产品、
客户、财务数字均为程序生成，**不代表任何真实企业**。行业增速引用了 TrendForce 公开口径
（见 `industry_supply_demand.source`），但需求侧存在明确标注的假设。