# P21 叠构与阻抗计算器 接口清单（规划）

> 前缀：`/api/stackup`　鉴权：计算接口可匿名限流访问；保存与模板需登录

## 1. 叠构

| 方法 | 路径 | 说明 | 主要参数 |
| --- | --- | --- | --- |
| POST | /projects | 保存叠构 | `name` `layer_count` `stack` `material_id` |
| GET | /projects | 我的叠构与模板 | `type=mine|public|team` |
| GET | /projects/{id} | 叠构详情 | `id` |
| PUT | /projects/{id} | 更新叠构 | 同上 |
| DELETE | /projects/{id} | 删除叠构 | 仅本人或团队管理员 |
| GET | /projects/{id}/report | 导出叠构与阻抗报告 | `format=pdf` |

## 2. 阻抗与损耗

| 方法 | 路径 | 说明 | 主要参数 |
| --- | --- | --- | --- |
| POST | /impedance/calc | 计算阻抗 | `topology` `target` `dk` `h` `w` `s` `t` `unit` |
| POST | /impedance/solve | 反求线宽线距 | 同上传入目标阻抗 |
| POST | /loss/estimate | 衰减估算 | `freq` `dk` `df` `h` `copper_oz` |
| GET | /records | 计算历史 | `page` `size` |

## 3. 板材库

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /materials | 板材列表（Dk/Df/Tg/类型） |
| POST | /materials | 新增板材（运营） |
| PUT | /materials/{id} | 更新板材参数并记录修改人 |
| GET | /materials/{id}/suppliers | 常备该板材的服务商 |

## 4. 关键字段

`stackup_project`：`user_id` `name` `layer_count` `stack_json` `material_id` `is_public` `is_team` `report_url`

`impedance_record`：`stack_id` `topology` `dk` `df` `h` `w` `s` `t` `z_calc` `z_target` `freq` `loss` `unit`

`material_base`：`brand` `model` `type` `dk` `df` `tg` `test_condition` `thickness_list` `enabled`

## 5. 错误码

| 码 | 含义 | 处理 |
| --- | --- | --- |
| 22001 | 叠构层序非法（信号层无参考平面） | 提示补齐参考层或调整为对称叠构 |
| 22002 | 总厚度超出公差 | 提示更换 PP 组合 |
| 22003 | Dk 缺失或待核 | 回退同类型板材并标注 |
| 22004 | 目标阻抗无法在工艺极限内实现 | 给出最接近可达区间 |
| 22005 | 模板不存在或已下线 | 提示选择其他模板 |
| 22006 | 无权限修改公共模板 | 仅运营可维护 |
