层：事实源（需求唯一事实源） ｜ 更新触发：需求/验收/附录变更（冲突以本文为准） ｜ 注册表：README
简体中文 | 英文简版待出（见 README.en.md 同步约定）
版本口径：MVP = 已跑通的可行性原型（檐柱一种构件 + 间数生成柱网 + D 模数 + GB/T 50001-2017 三视图框架）；V1 = 本 PRD 目标——建成一座清式面阔三间的硬山大木构架（= 数据格式冻结的 1.0.0 版本）。 单一事实源：本文件承载"为什么 / 做什么 / 范围 / 需求 / 验收 / 非功能"。
PROGRESS.md是实现状态矩阵，按本文FR-*/TC-*编号引用、不另立需求；冲突以本文为准。
标注约定：〔已定〕= README/PROGRESS/ADR/作者在整合稿中确认；〔待定〕= 需作者给则例/决策，本文不臆造；〔未验证〕= 未经实现或证据。
需求编号：FR-DAT 数据层 / FR-BLD 构建层 / FR-UI 交互层 / FR-DRW 图纸 / FR-ENG 工程与复现；NFR 非功能；验收 TC-P 正向 / TC-N 反向；开放问题 O。层级对应模块/子系统（DAT→data，BLD→core+bridge，UI→app，DRW→sheet，ENG→横切）。
引用约定：文中作者内部笔记（《基于"缝"的编码体系 v1.2》《参数化转译 v1.0》《硬山建筑的构件与参数》）均为纯文本引用，不内嵌 wiki-link / 脚注，以免被 Markdown 格式化工具破坏。
为中国古建研究者、遗产保护工作者与需要考据可信模型的创作者，把一座硬山建筑的大木构架（柱、梁架、桁檩、椽、望板）用"基于缝的编码体系 + 基于中国古代营造体系的参数化转译"描述为 JSON 数据，由 Python 粘合层转成 OpenSCAD 实例代码，一键产出 3D 模型（STL/OBJ）与可交付图纸（平面 / 立面 / 侧样，含尺寸标注），并结构化导出研究数据，保证参数化、可版本控制、可复现、可引用。
编码体系与参数化转译依据作者两份内部笔记：《基于"缝"的编码体系 v1.2：清式硬山建筑》《基于中国古代营造体系的参数化转译 v1.0：清式硬山建筑》。
- 现状〔已定〕：MVP 已跑通"檐柱一种构件 + 间数生成柱网 + D 模数 + GB/T 50001-2017 三视图框架"的完整管线（
bridge/pipeline、app/server、sheet/compose），端到端可复现。 - 痛点〔已定，作者确认〕：
- 手工 CAD / SketchUp 改一个尺寸要全图重排。
- 主流 3D 软件与研究数据脱节。
- 现成 BIM 软件缺乏针对中国古建筑的参数框架。
- 现成参数化工具（Grasshopper 等）门槛高、难版本化、难复现。
- 古建术语与坐标体系缺公开编码标准，各自为政。
- 爱好者 / 创作者制作相关资产有门槛。
docs/users.md的痛点仍以"骨架稿 +[TODO 求证]"存在；本 PRD 采纳作者此处确认的表述立论，后续补访谈/测绘证据再回填。
- 表达一座硬山大木构：建成面阔三间的简单木构（参考马炳坚《中国古建筑木作营造技术》及作者《硬山建筑的构件与参数》笔记），构件位置 = 三维缝交点 + 三维相对位置（各轴等价，不单列某一向）、朝向另计，可预览可导出。
- 数据可编辑调整：通过修改各构件的关键参数实现尺度变化。
- 数据可冻结和复现：保证版本化回溯。
- 数据可交付：结构化导出参数数据（CSV / XLSX +
model_spec.json）。 - 模型可交付：导出模型可在主流 3D 软件 / 游戏引擎正常使用，无坏面、三角面不过多。
- 图纸可交付：平面 / 立面 / 侧样（横剖） 含尺寸标注、轴线编号，达出版线。
- 外部可复现：≥1 位外部研究者按用户手册端到端跑通一座硬山。
V1（本版必做）：一座清式小式、面阔三间的硬山建筑大木构架（大木作结构骨架）。构件清单见附录 A，做法系数见附录 B。
- 交互：在模型上点选查看、编辑关键参数即时重算、生成与一键重建、导出。
- 数据：结构化导出 CSV / XLSX；
model_spec.json存档。 - 模型：STL / OBJ 分构件可辨识导出（V1 不出 glTF）。
- 图纸：平面（俯/仰）/ 立面 / 侧样横剖 + 纵剖，含尺寸标注 + 轴线编号。
- 交付：用户手册 / 复现教程、依赖锁定、Release；Windows 与大屏测试。
明确不做（V1 范围外）〔已定〕：大木作以外部分——墙体 / 屋面瓦作 / 正脊垂脊 / 台明 / 门窗装修；斗栱 / 铺作（大式带斗栱属后续）。
后续候选（非本版）：① 单位制一键换算（可变营造尺）；② 多项目并行管理；③ 清式悬山；④ 歇山 / 庑殿、大式带斗栱（引入斗口模数）；⑤ 宋式两坡顶（引入材份模数）；⑥ 宋式四坡顶；⑦ 宋式九脊殿。〔材份/斗口 V1 仅结构预留，见 O14〕
- 研究者（核心）：把一座面阔三间硬山的测绘数据整理为缝 + 构件 JSON，运行管线得 3D 模型与平面/立面/侧样图纸；改某跨距或某构件关键参数后模型与全部标注自动重算，无需全图重排；管理版本并导出研究数据备份。〔痛点 1–5〕
- 创作者 / 爱好者（次要）：在工作台选间数生成骨架、点构件改关键参数、下载可导入引擎 / 打印的模型。〔痛点 6〕
- 技术美术（次要）：调 D 与断面细分（FN）控制三角面，批量生成变体导入 3D 软件 / 引擎。〔痛点 6〕
| 类型 | 内容 | 应对 |
|---|---|---|
| 设计·术语 | 缝名取宋（槫/栿）、构件名取清（檩/梁）混用 | 已决方向（O1）：轴线/缝名目前清式无更好表达，沿用宋式；构件名分明清、各自体现做法、参数可略有差别。构件 id 拼写与映射待此方向落 ADR 细化 |
| 设计·则例 | 尺寸含 D + n寸、或 备选式 |
已定（O15）：尺寸 = 对具名量的线性表达式（见 FR-BLD-10）；"或"式取作者选定默认〔待定〕；寸的 mm 基准默认 营造尺/10、V1 锁常量〔待定〕 |
| 实现 | 28 类构件 + 斜置椽 + 矩形断面 + 举架曲线能否被 OpenSCAD 稳定表达 | 先做一榀最小可行（柱+一梁+一檩+几椽）跑通再扩量 |
| 实现·版本 | OpenSCAD 跨版本能力漂移（OBJ 直出仅新版、无 GPU PNG 失败） | 保留 trimesh / PNG-skip 兜底；只调官方 CLI，禁第三方封装；记录最低验证版本（FR-ENG-2） |
| 依赖 | 复现依赖外部二进制 + 未锁 Python 版本 | 依赖锁定 + 记最低验证版本（FR-ENG-2）；不引入 openscad-cli 封装 |
| 测试 | 研究者 / 创作者 / TA 真实工作流适配 | 基本完成后按三种流程各跑一遍（FR-ENG-1） |
| 依赖·导入 | 外部雕刻件破坏纯文本可复现、OpenSCAD 不吃 glTF/FBX | V2+（O13）：下游 mesh 合并 + 拷件入项目记哈希 |
优先级：P0=V1 DoD 必需；P1=V1.x；P2=后续。验收见 §5。
| ID | 需求 | 优先级 | 依赖 | 验收 |
|---|---|---|---|---|
| FR-DAT-1 | 缝体系实装：定义各缝走向与交点规则，实装 FU 栿缝 / TUAN 槫缝 / TUANJIAN 槫间缝；缝可带三维定位（横缝含高程） | P0 | — | TC-P001 |
| FR-DAT-2 | 构件族类型注册：清式硬山 28 类（附录 A），拼音 id 规则 ^[a-z][a-z0-9]*_[0-9]+$ 不变 |
P0 | O1 | TC-P001 |
| FR-DAT-3 | 构件基本参数与实例模型：类型 · 关联缝 · 关联构件(parent) · 位置 = 三维缝交点 + 三维相对偏移 Δ · 朝向(orientation) · 每尺寸 = k×basis + c×(寸/分) 或 {abs,unit} 覆盖（成员尺寸互相引用为后续，V1 不做；项目量如明间面宽可引）· 可选 src=公式出处 · 断面；单一 active basis（V1=D）、可编辑；显示单位正交格式化 |
P0 | FR-DAT-1, FR-BLD-10 | TC-P002, TC-P014 |
| FR-DAT-4 | 项目数据版本管理：$version；随版本存 全局参数(basis / 寸 / display 单位 + mm_per)、缝数据、构件数据、附件（导入资产，见 O13）；破坏性变更走迁移说明 |
P0 | — | TC-P004 |
| FR-DAT-5 | 批量生成同类构件：pattern 枚举 / 谓词（整排檐椽、多榀梁架），确定性展开、id 稳定 | P1 | FR-DAT-1 | TC-N003 |
| FR-DAT-6 | 数据交付导出：结构化 CSV / XLSX（构件明细 + 关键参数 + 所属缝 + 可读名 + 参考算法 src + seam_id/gb_no）+ model_spec.json 存档 |
P0 | FR-DAT-3, FR-BLD-9 | TC-P015 |
| ID | 需求 | 优先级 | 依赖 | 验收 |
|---|---|---|---|---|
| FR-BLD-1 | 缝基本参数：位置——走向 + 高程解析（横缝 CAO·F/B / TUAN / FU 供 z，JIAN 纵缝不供） | P0 | FR-DAT-1 | TC-P001 |
| FR-BLD-2 | 构件实例参数：相对位置——三维 Δ；位置解析 = 缝交点 + Δ（叠层构件从承托 + 举架派生 z） | P0 | FR-BLD-1 | TC-P001 |
| FR-BLD-3 | 构件实例参数：朝向 / 旋转 → orientation（绕 z + 椽斜面坡度），非圆柱构件必需 |
P0 | FR-BLD-2 | TC-P001 |
| FR-BLD-4 | 构件实例参数：断面——圆（柱 / 檩近圆）+ 矩形（梁 / 枋 / 垫板 宽×厚）+ 椽小断面；FN 控细分 | P0 | — | TC-P001, TC-P009 |
| FR-BLD-5 | 一榀横架生成：柱网 + 进深 + 举架 → 单榀梁架 + 桁檩三件套 + 瓜柱 | P0 | FR-BLD-1–4 | TC-P001 |
| FR-BLD-6 | 屋顶骨架：椽（檐 / 花架 / 脑）沿举架斜面 + 大 / 小连檐 + 望板 | P0 | FR-BLD-1–4 | TC-P003 |
| FR-BLD-7 | SCAD 产物验证：codegen 发射 z / 旋转 / 多断面 / 斜椽实例；STL / OBJ / SVG / PDF 兼容（V1 不 glTF） | P0 | FR-BLD-1–6 | TC-P003 |
| FR-BLD-8 | 模型交付质量：STL/OBJ 无非流形 / 自交坏面、面数在阈值内、单位与坐标朝向导入正确、按构件分组可辨识 | P0 | FR-BLD-4,7 | TC-P009, TC-N006 |
| FR-BLD-9 | 导出可读实例名（P1）：V1 采用 (a) sidecar——每实例可读名（GB 轴线号 / 缝编码 / 中文方位，默认 GB；随术语切换）落在 model_spec.json + CSV + §4 面板；主 id 短稳、标签派生；中文方位待 O1。o/g 名，模型文件内逐构件具名属 (b)/(c) 增强（trimesh 装配已证可行，端到端待 M1 真几何复验） |
P1 | FR-BLD-8, O17 | TC-P010 |
| FR-BLD-10 | 尺寸表达式引擎：V1 解析 k×basis + c×寸/分（basis=D；寸=320mm/10 可配，见 O16/G1）的线性式，可含项目量（明间面宽等）；成员尺寸互相引用（如 三架梁厚=4/5·五架梁厚）为后续、V1 不做；每式记 src（参考算法出处，现马炳坚） |
P0 | FR-DAT-3 | TC-P014 |
| ID | 需求 | 优先级 | 依赖 | 验收 |
|---|---|---|---|---|
| FR-UI-1 | 模型点选 / 查看：three.js 拾取构件 → 显示其基本参数（类型 / 关联缝 / 关联构件 / 位置 / 朝向 / 尺寸） | P0 | FR-DAT-2,3 | TC-P002 |
| FR-UI-2 | 关键参数编辑（草稿态）：改 basis 值 / 尺寸 coeff / 设 {abs,unit} → 内存即时重算重建、不写盘；保存才落盘（先校验、失败不落坏）；属性编辑按 O10 决定 |
P0 | FR-DAT-3, FR-BLD-10 | TC-P002, TC-N004 |
| FR-UI-3 | 构件筛选：按族类 / 所属缝 / 标高过滤并联动预览高亮；仅影响显示，导出全量 | P1 | FR-DAT-3, FR-UI-1 | TC-P005 |
| FR-UI-4 | 构建错误分级：无效缝编码 / 缺定位 / 断面非法 / 表达式环 → 定位到字段 / 缝 | P1 | FR-DAT-3, FR-BLD-10 | TC-N001 |
| FR-UI-5 | 项目与显式保存（三层存储）：data/=类型目录/参考示例+schema（入库）；presets/=仓库内示例项目（带"示例"标记）；用户项目在仓库外。保存写当前项目（先校验后原子落盘）；编辑示例须先「另存为」、不就地覆盖；列表区分示例/用户；build/generated/ 退回临时缓存 |
P1 | FR-DAT-4, FR-UI-2 | TC-P006, TC-P012 |
| FR-UI-6 | 撤销 / 重做：回退 / 重做会话内编辑动作；内存草稿栈、不写盘；不跨重启、不回退生成结果；栈深度上限见 NFR | P1 | FR-UI-2 | TC-P011, TC-N007 |
| ID | 需求 | 优先级 | 依赖 | 验收 |
|---|---|---|---|---|
| FR-DRW-1 | 尺寸标注：界线 / 尺寸线 / 45° 起止 / 数字（mm 不带单位），多层（定位 + 总），值从 resolver 推导 | P0 | FR-BLD-2 | TC-P003 |
| FR-DRW-2 | 横剖（侧样）+ 纵剖图：一榀梁架叠檩 + 瓜柱 + 举架，大木构关键交付图 | P0 | FR-BLD-5, FR-DRW-1 | TC-P003 |
| FR-DRW-3 | 定位轴线：线型（0.25b 单点长画线）+ 编号圆（缝 id 主键 + gb_no 自动推导双轨） |
P0 | FR-DAT-1 | TC-P007 |
| FR-DRW-4 | 平面图：俯视 / 仰视 + 剖切符号指向侧样 | P1 | FR-BLD-6, FR-DRW-2 | TC-P003 |
| FR-DRW-5 | 立面图：多方向立面 + 剖切符号 | P1 | FR-DRW-2 | TC-P003 |
| FR-DRW-6 | 图层分组：轴线 / 轮廓 / 标注 / 图框 / 标题栏语义分组 | P1 | FR-DRW-1 | — |
| ID | 需求 | 优先级 | 依赖 | 验收 |
|---|---|---|---|---|
| FR-ENG-1 | 用户手册 / 复现教程：外部研究者端到端跑通一座硬山；含 Windows 与大屏测试 | P0 | 全部 | TC-P008 |
| FR-ENG-2 | 依赖锁定：钉 reportlab/fontTools/trimesh + 记录 OpenSCAD 最低验证版本 | P1 | — | TC-P008 |
| FR-ENG-3 | Release 流程：CHANGELOG + git tag + Releases 附样例产物 | P1 | — | — |
| FR-ENG-4 | CITATION.cff / DOI：学术引用入口（编码体系引用另见 LICENSE-docs） | P1 | — | — |
| FR-ENG-5 | 构建缓存 / 增量（构件上百后） | P2 | FR-BLD-7 | — |
状态
- 构件：
未定义（缺关键参数）→已定位（缝交点 + Δ + 朝向 + 断面齐备）→可构建（resolver 通过）→失败（缺项 / 冲突 / 表达式环，附原因）。 - 项目：
草稿→已解析→已构建→已出图。 - 编辑（工作台）：
已保存↔有未保存改动(脏)；撤销 / 重做栈（会话内、仅内存）；保存 = 校验 → 写当前项目 → 清脏。〔FR-UI-2/5/6〕 - 构建：
排队→渲染中（timeout=180）→成功/失败/超时。
规则（当…则…）
- 当构件
axes非"一横一纵"或缺定位时，则 resolver 抛错定位字段，不静默z=0。〔FR-BLD-1/2〕 - 当某尺寸为表达式
k×basis + c×寸（或引用他件 / 明间面宽）时，则按拓扑序求值成 mm、再交 OpenSCAD；出现环则报错定位。〔FR-BLD-10〕 - 当编辑
basis值时，则全体coeff表达式项重定标、{abs}覆盖项不动；切显示单位仅格式化、不改存储。〔FR-UI-2, FR-DAT-3〕 - 当在面板编辑时，则仅内存草稿重算、不写盘；当「保存」时，则先校验后原子写当前项目；示例项目禁止就地覆盖、转「另存为」。〔FR-UI-2/5〕
- 当可撤销动作时入栈；撤销 / 重做回退内存态、不改盘。〔FR-UI-6〕
- 当导出检出坏面 / 面数越阈值时，则 FR-BLD-8 判失败并定位。〔NFR 模型质量〕
流程：输入 → schema + 缝 + 表达式 校验 → resolve（mm spec）→ codegen（.scad：位置 / 朝向 / 断面 / 斜椽）→ OpenSCAD 导出（STL/OBJ 分构件 + SVG 三视 + 剖）→ 网格质量检查（FR-BLD-8）→ compose 图纸（图框 / 标题栏 / 标注 / 轴线编号，SVG+PDF 同源）→ 归档 model_spec.json + 导出 CSV/XLSX（FR-DAT-6）。
数据（关键字段）：构件实例 = id · type · axes（每条关联缝 → {seam, offset}，offset 三维 Δ）· （可选）parent（附属 / 承接，如 枋·垫板→檩）· orientation · section（形状∈圆/矩形，每尺寸 = 表达式 k×basis + c×寸… 或 {abs,unit}）· （可选）attrs（O10）· note · label（派生可读名）。轴对象含三维定位（横缝带高程）。文件 = axes.json + members/*.json。
逆向：删除构件 → 移出并级联检查依赖其缝 / 承接 / 被引用尺寸者，提示受影响实例、不静默删；改间数 → pattern 重排（id 稳定、撞车换号并报告）；撤销 / 重做 = 编辑动作逆 / 正向（会话内）。
兼容：$version 升级附迁移说明；MVP 仅柱网项目新版打开按 $version + 单位处理（默认不破坏）；示例/用户项目分离；未保存改动离开须提示。
布局以选定的 方向 C「缝·数据工作台」 为准（视觉 / 信息组织参考 refs/ui-seam-grid.html，决策见 ADR-0008）：顶部 功能栏 ｜ 左侧 项目参数区 + 筛选 ｜ 主视图 = 平面"井字轴线网"为 hero（缝距带尺寸标注，点一条缝即联动筛选 / 开该缝面板）｜ 次级 tab 立面 / 侧样 / 轴测 3D / 构件清单 ｜ 右上 悬浮参数面板（一次一个）｜ 底部 状态栏。
| 区域 | 信息项 | 组件 | 说明 |
|---|---|---|---|
| 功能栏 | 新建 / 打开 | 下拉 | 新建 → 读 presets/；打开 → 读项目 |
| 功能栏 | 保存 / 另存为 | 下拉 | ⌘S；示例项目转「另存为用户项目」、不就地覆盖（FR-UI-5） |
| 功能栏 | 撤销 / 重做 | 下拉 | ⌘Z / ⇧⌘Z 回退 / 重做会话内编辑（FR-UI-6） |
| 功能栏 | 导出 | 下拉 | 全部 / 模型 STL·OBJ / 平面·立面·侧样 SVG+PDF / 数据表 CSV·XLSX |
| 左侧·参数 | 当前项目 | 下拉 | 项目名称（标"示例 / 用户"来源） |
| 左侧·参数 | 术语显示 | 单选 | GB / 缝编码 / 中文方位，影响导出构件名（FR-BLD-9；中文方位待 O1） |
| 左侧·参数 | 单位 | 单选 | mm / 营造尺，纯格式化不改存储（FR-DAT-3） |
| 左侧·参数 | 模数 | 单选 + 数字 | basis：D / 斗口 / 材（一次一个，V1=D）；改值 → 全体 coeff 项重定标（FR-BLD-10） |
| 左侧·参数 | 间：面阔 & 进深 | 数字 | 按间数算默认、支持手改（奇数间，MVP G17） |
| 左侧·参数 | 一键生成 | 按钮 | 生成模型与图纸、更新缝网 |
| 左侧·筛选 | 族类 / 缝 | 多选 | 过滤构件并联动主视图高亮；仅影响显示、导出全量（FR-UI-3） |
| 主视图 | 平面轴线网（hero） | SVG | 井字缝网 + 缝距尺寸标注；点一条缝 → 筛选 + 开该缝面板 |
| 次级 tab | 立面 / 侧样 / 轴测 3D / 构件清单 | tab | 轴测用 three.js，点构件 → 开面板；清单列 id 与全部属性 |
| 悬浮面板 | 构件 / 缝 参数 | 悬浮（单个） | 随选中切换、一次一个；构件面板改 coeff / 填 abs、公式悬浮显示 src 出处；缝面板显该缝构件 |
| 状态栏 | 运行 / 项目信息 | 文字 | 正在生成 / 导出；缝数·构件数·最后保存；示例换算注记 |
空 / 异常态〔须实现〕：项目空 → 引导生成；构建失败 → 分级错误定位字段 / 缝 / 环；无 / 旧 OpenSCAD → 提示最低版本 + OBJ/PNG 兜底说明；导出不达标 → 报坏面 / 超面数。
正向
TC-P*、反向TC-N*；具体则例值以附录 B / 作者笔记为准。
- TC-P001 建成骨架：面阔三间、给定 D → 生成柱 + 五架 / 三架梁 + 瓜柱 + 檐 / 金 / 脊桁檩三件套 + 椽望 → 预览成功、≥3 类构件、每构件三维位置 + 朝向 + 断面齐备。
- TC-P002 关键参数编辑驱动尺度：改檐檩径 / 金柱位置 → 内存即时重算、预览更新（未写盘）；保存后重开仍在。
- TC-P003 出可交付图：平面 / 正·侧立面 / 横剖侧样 PDF，均含尺寸标注（值 = resolver）、侧样含梁叠檩 + 举架。
- TC-P004 版本化：带
$version正常解析；缺 → 按基线并提示；不兼容 → 可读错误。 - TC-P005 筛选联动：按族类过滤 → 表收敛 + 预览高亮；导出仍全量。
- TC-P006 项目保存：写选定项目目录（非覆盖
build/generated）→ 列表可切换。 - TC-P007 轴线编号双轨：平面端部显
gb_no（横字母 / 竖数字，跳 I/O/Z）+ 图框内「编号↔缝编码」对照。 - TC-P008 外部复现：干净环境按
FR-ENG-1手册 + 锁定依赖 + 最低 OpenSCAD 版本跑通（含 Windows / 大屏）。 - TC-P009 模型质量达标：OBJ/STL 在 Blender/Unity 打开 → 无非流形 / 自交、三角面 ≤ 阈值、按构件可分选、单位 / 朝向正确。
- TC-P010 导出可读实例名：OBJ
g/o名按所选编码可读（默认 GB）；切编码重导名随之变；主 id 稳定。 - TC-P011 撤销 / 重做：改参数 → 撤销回原值（未写盘）→ 重做；保存前撤销不改磁盘。
- TC-P012 示例项目另存：打开
presets/示例 → 改 → 保存引导「另存为用户项目」、原示例不被覆盖。 - TC-P013 基准 / 单位 / 重定标：改
basis值 → 全体 coeff 尺寸重算、abs 不动；切显示 mm↔营造尺 → 仅显示变、存储与几何不变。 - TC-P014 尺寸表达式引擎：
金柱径 = D + 1寸、三架梁厚 = 4/5·五架梁厚（引用他件）正确求值为 mm；构造引用环 → 检测报错并定位。 - TC-P015 数据交付：导出 CSV / XLSX 含构件明细 + 关键参数 + 所属缝 + 可读名 +
seam_id/gb_no；model_spec.json存档可回读。 - TC-N001 缺几何定义：某梁缺定位 → 失败且定位字段，不出错误
z=0模型。 - TC-N002 偶数间：面阔 4 间 → 明确报错。
- TC-N003 pattern 撞车：改间数致 id 冲突 → 冲突者换新号并报告，合法不受影响。
- TC-N004 非法写目标：保存到非法 target → 4xx 且源数据未破坏。
- TC-N005 旧版 OpenSCAD：无原生 OBJ / 无 GPU → OBJ 走 trimesh 兜底或
[warn]、PNG 跳过，主产物仍出。 - TC-N006 模型质量不达标：某构件非流形 → FR-BLD-8 判失败、定位。
- TC-N007 未保存离开 / 空栈 / 表达式环：脏改动离开提示；空栈撤销无副作用；尺寸引用环 → 报错定位、不出错模型。
| ID | 维度 | 约束 |
|---|---|---|
| NFR-1 | 性能 | 全量重建时长随规模上升（MVP 6 次调用 3–8s）；面阔三间可控，上百触发 FR-ENG-5 缓存；撤销栈深度上限〔待定〕；具体阈值〔待实测〕 |
| NFR-2 | 可靠性 | 不无故闪退；异步构建失败保留上次产物并回报；OpenSCAD 跨版本兜底（STL/SVG 稳，OBJ/PNG 降级） |
| NFR-3 | 可复现 | 多平台可复现：依赖锁定 + 最低验证 OpenSCAD 版本 + $version（含 basis / 寸 / display）；数据即事实源、可 diff |
| NFR-4 | 安全 | 本地：仅 127.0.0.1、无鉴权；JSON 走 schema 校验；/files/ 路径穿越防御保留；LAN/hosted 须重评（O7） |
| NFR-5 | 一致性 | 显示信息 = 导出信息；术语跨 PRD/原型/图纸/导出一致（构件=member） |
| NFR-6 | 模型交付质量（目标 5） | STL/OBJ 水密、无非流形 / 自交 / 退化面；三角面 ≤ 阈值〔待定〕（受 FN 与构件数影响）；单位 / 坐标朝向在 Blender/Unity/Unreal 导入正确；按构件分组可辨识 |
| 版本 | 日期 | 变更 | 确认状态 |
|---|---|---|---|
| v0.1–v0.11 | 2026-09-22 | 首版统一基线 → MVP/V1 口径 → 六条 DoD → 关键参数编辑 / 模型质量 → 去 wiki-link → 语义层码编号 → 导出可读名 → z 标高缝模型 → 撤销/显式保存 → 项目存储三层 → 单一 basis 定稿 | 逐版被后版取代 |
| v0.12 | 2026-09-22 | 采纳作者整合稿为主骨架重写：结构改为 概述 / FR 总表 / 处理逻辑 / 交互设计 / 非功能 / 修订；FR 全面重编号（缝实装→DAT-1、$version+存储→DAT-4、构件模型+basis→DAT-3 等，映射见附录 D）；痛点补 2、3；目标增至 7（新增"数据可交付 CSV/XLSX"=FR-DAT-6）；附录 B 清代小式做法表填入散落〔待定〕系数；单位/材份/斗口"换算与启用"移入后续（V1 仅 D + 显示换算）；新增 FR-BLD-10 尺寸表达式引擎（k·basis+c·寸+引用他件）；位置措辞改"三维缝交点 + 三维相对位置"、朝向单列；O1 术语"缝沿用宋式、构件分明清"记为已决；V1 不出 glTF；同步 PROGRESS.md 重映射 |
草稿·待评审（生成 ≠ 通过） |
| v0.13 | 2026-09-22 | 交互微调：构件参数面板由"可开多个堆叠"改为一次只显示一个（点哪个构件显示哪个、替换当前；按色对应、可关闭） | 用户要求 |
| v0.14 | 2026-09-22 | 前端方向选定 C「缝·数据工作台」（ADR-0008）：§4 重写为 C 的组织（平面井字轴线网为 hero + 点缝联动 + 次级 tab + 单个悬浮面板 + 左侧参数/筛选）；frontend-lab/ 撤销，C 移至 refs/ui-seam-grid.html、A/B 删除（git 保史） |
用户选 C 方向 |
| v0.15 | 2026-09-22 | 记入 M0 闸门决策：寸 1尺=10寸=100分=320mm(可配)、举架(步架均等·率 0.5/0.6/0.7)、山面/叠合做法(山柱→垫板→檩、梁半包围、枋上皮=柱上皮)、presets/；FR-BLD-10 收窄——V1 表达式仅 k·basis+c·寸/分(+项目量)，成员尺寸互引后续；新增 src(参考算法/出处，现马炳坚) 贯穿 FR-DAT-3 / FR-DAT-6"参考算法"列 / §4 公式悬浮；"或"式默认取简 |
用户答 G1/G3/G4/G5/G7 |
后续：仅经授权整改才更新基线；纯评审不改原文。
具体使用构件按实际定。做法系数见附录 B。
- 柱：檐柱、金柱
- 桁檩：檐枋、檐垫板、檐檩 / 金枋、金垫板、金檩 / 脊枋、脊垫板、脊檩
- 梁架：穿插枋、抱头梁、随梁枋、五架梁、三架梁、脊瓜柱、金瓜柱
- 屋顶：檐椽、脑椽、花架椽、小连檐、大连檐、望板
来源：作者整理，公式出处
src现均记 马炳坚《中国古建筑木作营造技术》（数据层 per-dimsrc记录；多维表设"参考算法"列；构件属性公式悬浮提示，见 §4）。多"或"式默认取更简者〔个别可后改〕。 已定做法（2026-09-22）：① 寸——1 尺 = 10 寸 = 100 分 = 320mm（320mm 为通用基准、可配，非写死）。② 举架——步架（进深）均等，逐檩升高 = 步架 × 举架率；示例七檩按0.5 / 0.6 / 0.7。③ 山面/叠合——山柱上承垫板、垫板上承檩；檩与垫板被梁半包围；枋上皮与柱上皮持平。
柱类
| 构件 | 高 | 径 |
|---|---|---|
| 檐柱（小檐柱） | 11D 或 8/10 明间面宽 | D |
| 金柱（老檐柱） | 檐柱高加廊步五举 | D + 1寸 |
| 中柱 | 按实计 | D + 2寸 |
| 山柱 | 按实计 | D + 2寸 |
| 重檐金柱 | 按实计 | D + 2寸 |
梁类
| 构件 | 长 | 高 | 厚 | 备注 |
|---|---|---|---|---|
| 抱头梁 | 廊步架加柱径一份 | 1.4D | 1.1D 或 D+1寸 | |
| 五架梁 | 四步架加 2D | 1.5D | 1.2D 或 金柱径+1寸 | |
| 三架梁 | 二步架加 2D | 1.25D | 0.95D 或 4/5 五架梁厚 | |
| 递角梁 | 正身梁加斜 | 1.5D | 1.2D | |
| 随梁 | D | 0.8D | ||
| 双步梁 | 二步架加 D | 1.5D | 1.2D | |
| 单步梁 | 一步架加 D | 1.25D | 4/5 双步梁厚 | |
| 六架梁 | 1.5D | 1.2D | ||
| 四架梁 | 5/6 六架梁高 或 1.4D | 4/5 六架梁厚 或 1.1D | ||
| 月梁（顶梁） | 顶步架加 2D | 5/6 四架梁高 | 4/5 四架梁厚 | |
| 长趴梁 | 1.5D | 1.2D | ||
| 短趴梁 | 1.2D | D | ||
| 抹角梁 | 1.2D～1.4D | D～1.2D | ||
| 承重梁 | D+2寸 | D | ||
| 踩步梁 | 1.5D | 1.2D | 用于歇山 | |
| 踩步金 | 1.5D | 1.2D | 用于歇山 | |
| 太平梁 | 1.2D | D |
枋类
| 构件 | 长 | 高 | 厚 |
|---|---|---|---|
| 穿插枋 | 廊步架 + 2D | D | 0.8D |
| 檐枋 | 随面宽 | D | 0.8D |
| 金枋 | 随面宽 | D 或 0.8D | 0.8D 或 0.65D |
| 上金、脊枋 | 随面宽 | 0.8D | 0.65D |
| 燕尾枋 | 随檩出梢 | 同垫板 | 0.25D |
檩类
| 构件 | 径 |
|---|---|
| 檐、金、脊檩 | D 或 0.9D |
| 扶脊木 | 0.8D |
垫板类
| 构件 | 高 | 厚 |
|---|---|---|
| 檐垫板、老檐垫板 | 0.8D | 0.25D |
| 金、脊垫板 | 0.65D | 0.25D |
瓜柱类
| 构件 | 宽 | 高 | 厚 |
|---|---|---|---|
| 金瓜柱 | D | 按实计 | 上架梁厚 × 0.8 |
| 脊瓜柱 | D～0.8D | 按举架 | 0.8 三角梁厚 |
| 角背 | 一步架 | 1/2～1/3 脊瓜柱高 | 1/3 自身高 |
角梁类
| 构件 | 高 | 厚 |
|---|---|---|
| 老角梁 / 仔角梁 / 由戗 | D | 2/3 D |
| 凹角老角梁 / 凹角梁盖 | 2/3 D | 2/3 D |
椽类
| 构件 | 宽 | 厚 | 径 |
|---|---|---|---|
| 圆椽 | 1/3 D | ||
| 方、飞椽 | 1/3 D | 1/3 D | |
| 花架椽 | 1/3 D | 1/3 D | |
| 罗锅椽 | 1/3 D | 1/3 D |
连檐 / 瓦口 / 衬头木
| 构件 | 宽 | 厚 |
|---|---|---|
| 大连檐 | 0.4D 或 1.2 椽径 | 1/3 D |
| 小连檐 | 1/3 D | 1.5 望板厚 |
| 瓦口 | 同横望板 | |
| 衬头木 | 1/3 D |
望板
| 构件 | 厚 |
|---|---|
| 横望板 | 1/15 D 或 1/5 椽径 |
| 顺望板 | 1/9 D 或 1/3 椽径 |
| ID | 问题 | 状态 / 结论 |
|---|---|---|
| O1 | 术语统一：缝名取宋（槫/栿）、构件名取清（檩/梁） | 已决方向：轴线/缝沿用宋式（清式无更好表达）、构件名分明清、参数可略有差别；构件 id 与映射待落 ADR（影响 FR-DAT-2 / FR-BLD-9 中文方位） |
| O5 | 则例数值 | 部分已给（附录 B）；"或"式默认选择、举架各步率、山柱收头、寸的 mm 基准 仍〔待定〕 |
| O7 | 非本地（LAN/hosted）部署意图 | 默认否（NFR-4） |
| O10 | 属性元数据（材质 / 数量 / 考据）是否进 V1 | 默认仅预留字段、不做编辑 UI；请作者定 |
| O11 | 导出保真度 / 格式 | 已定：V1 只 STL/OBJ（OBJ 按构件分组带名）、不出 glTF（后续评估）；三角面阈值需实测 |
| O12 | 项目存储位置 | 已定：data/ 类型目录+示例；presets/ 仓库内示例项目（编辑另存为）；用户项目仓库外；目录名 presets/examples 待定 |
| O13 | 模型导入 / 外接资产 | V2+：OpenSCAD 不吃 glTF/FBX → 下游 mesh 合并（新 ADR）；导入件拷进项目记哈希；刚体不参数化 |
| O14 | 单位 · 基准 · 重定标模型 | 已定：单一 active basis（V1=D，一次一个、不并存不换算）；寸/材/斗口 启用属 G7 后续；显示单位正交格式化 |
| O15 | 尺寸表达式：k×basis + c×寸、或 备选式、引用他件尺寸 / 明间面宽 |
已定支持（FR-BLD-10）；寸 mm 基准 + "或"默认值〔待定·作者〕 |
| O16 | "寸"的绝对基准 | 已定（G1）：1 尺 = 10 寸 = 100 分 = 320mm（320 为通用基准、可配 → 寸=32mm、分=3.2mm）；可变营造尺属后续 G14 |
| O17 | 具名导出路线 | OpenSCAD OBJ 导出实测无 o/g 名（spike/README.md 探针，版本无关），FR-BLD-9 "OBJ 带名"不成立。待决（作者）：(a) sidecar（model_spec/CSV 带 label、模型为融合体；最省、守 V1 不出 glTF）/ (b) 逐构件导出 + Python 拼接带 o <label> 的 OBJ（单文件可带名、不用 glTF、但逐构件导出慢）/ (c) glTF（trimesh.Scene 节点名，最规范但推翻"V1 不出 glTF"）。默认 (a)；定前 FR-BLD-9 阻塞。影响 FR-BLD-9 / FR-DAT-6 / 模型交付。→ 已实测可行（(b)/(c) 都成立）：trimesh 逐实例装配 → 单 .obj 出多 o <label>、glTF 保留节点名；优化：每类型(或每尺寸变体)导出一份基础 mesh + resolver 给每实例世界变换(translate/rotate)与 label，避免 N 次 OpenSCAD 调用（≤28 base mesh）。决策(2026-09-22)：V1 暂用 (a)；(b)/(c) 保留、端到端待 M1 真几何复验后再决定是否升级"单文件带名"。 |
| 旧 | 新 | 旧 | 新 | |
|---|---|---|---|---|
| FR-DAT-4 缝实装 | FR-DAT-1 | FR-BLD-1/2/3 z/朝向/断面 | FR-BLD-1/2/3/4（拆缝位置/构件位置/朝向/断面） | |
| FR-DAT-2 注册 | FR-DAT-2 | FR-BLD-4/5/6 一榀/屋顶/codegen | FR-BLD-5/6/7 | |
| FR-DAT-1+6 数据模型+basis | FR-DAT-3 | FR-BLD-7/8 质量/可读名 | FR-BLD-8/9（可读名 P0→P1） | |
| FR-DAT-3 $version | FR-DAT-4（+ 附件/存储） | （新） | FR-DAT-6 数据交付、FR-BLD-10 表达式引擎 | |
| FR-DAT-5 pattern | FR-DAT-5 | FR-DRW-1/2/3/5 | FR-DRW-1/2(横+纵剖)/3/6；新增 FR-DRW-4/5 平面/立面 | |
| FR-UI-1..6 | FR-UI-1..6（号不变） | FR-ENG-5 Windows | 并入 FR-ENG-1；缓存 FR-ENG-6→FR-ENG-5 |
本 PRD 为草稿，生成 ≠ 评审通过。下一步：① 作者补附录 B 的"或"默认 / 举架各步率 / 寸基准（O5/O15/O16）；② O1 术语 ADR；③「原型」模式做一榀硬山最小可行演示（验 FR-BLD-1..10）。