Skip to content

PROGRESS.md

Latest commit

 

History

History
172 lines (130 loc) · 18.1 KB

PROGRESS.md

File metadata and controls

172 lines (130 loc) · 18.1 KB
Raw

CHBIM 实现状态矩阵（功能矩阵 · 随开发滚动更新）

口径说明（2026-09-22）：需求以 docs/PRD.md 为单一事实源。本文件退居实现状态矩阵——只做状态跟踪、并引用 PRD 的 FR-DAT/BLD/UI/DRW/ENG-* 与 TC-* 编号，不再定义需求。二者冲突以 PRD 为准。 版本命名：MVP = 已跑通的可行性原型（檐柱 + 间数生成柱网 + D 模数 + GB/T 50001-2017 三视图框架，即本文原「V1 目标状态」）；V1 = 硬山建筑大木构架目标（= SemVer 1.0.0，度量口径见 PRD「V1 七条 DoD」）。原「1.0.0 毕业四条件」已并入 V1 七条 DoD（映射见文末「版本策略」）。 落地：分阶段实施见 docs/plan-v1-roadmap.md（现从 M0 起步）；/api+spec 契约草案见 docs/contract-v1-api-schema.md。

图例：✅ 已实现 · 🚧 进行中 · ⬜ 未开始 · 💡 需求池（已接受 · 待排）。优先级（未完成项）：[P0] V1（硬山大木构）必需 · [P1] V1.x · [P2] V2+/远期。

MVP 基线状态（原「V1 目标状态」）

说明：本节 ⬜ 未完成项凡标 [P0] 者，即 V1（硬山大木构）的必做需求，已因目标升级从原 [P1] 提升；其完整定义、优先级与验收以 docs/PRD.md FR 表为准。V1 出项（本矩阵仍列但本版不做）：斗栱 / 铺作（G4、PUZUO/TIAO 缝）、屋面瓦作、材份/斗口第二模数（G7）、节点式 3D 编辑、隐线消隐、比例尺。

整体模数

  • ✅ 整体模数 D（柱径）由用户输入，覆盖默认
  • ✅ 模数表达式 nD 由 resolver 求值为 mm
  • ⬜ 尺寸表达式引擎：V1 k×basis + c×寸/分 + 项目量（明间面宽），成员互引后续；单一 active basis（V1=D） [P0]（→ PRD FR-DAT-3 / FR-BLD-10）

轴线类型（缝）

  • ✅ 槽缝 CAO（横缝，定位 y）
  • ✅ 间缝 JIAN（纵缝，定位 x，含 JIAN_0 间中缝/明间中线）
  • ✅ 槫缝 TUAN（MVP 仅作辅助线显示于俯视图；V1 实装定位 → PRD FR-DAT-1）
  • ⬜ 栿缝 FU / 槫间缝 TUANJIAN [P0]（V1 梁架·桁檩定位必需 → PRD FR-DAT-1）
  • 💡 铺作缝 PUZUO / 跳心缝 TIAO（斗栱出跳）——V1 出项（硬山按无斗栱处理，见 G4）

构件

  • ✅ 檐柱 yanzhu（柱径 1D，柱高 11D）
  • ⬜ V1 硬山构件族：金柱 / 檐·金·脊（枋·垫板·檩）/ 五架梁·三架梁·抱头梁·穿插枋·随梁枋·脊·金瓜柱 / 檐·花架·脑椽·连檐·望板 [P0]（V1 目标 1：建成面阔三间、≥3 类 → PRD FR-DAT-2 & 附录 A）
    • 术语：缝名取宋（槫/栿）× 构件名取清（檩/梁），构件 id 与映射待 PRD O1 决策后定
  • 🚧 断面参数化：圆 / 矩形 codegen 已可发射（rect_bar/round_bar + 朝向，一榀样例验证过）；全类型接数据待做 [P0]（→ PRD FR-BLD-4）
  • 🚧 一榀横架生成：generate_layout(with_frame=True) 已自动出 柱网+五架梁+前后檐檩+脊檩+檐椽（举架率 G4·附录B 简化式，随 D 重定标，端到端 OpenSCAD NoError）；金柱/金桁三件套/瓜柱/任意进深通式 待做 [P0]（→ PRD FR-BLD-5）
    • 工作台「生成」可勾「含一榀梁架」；手写示例 presets/one-bay-demo/ 保留作对照

位置语义（ADR-0004）

  • ✅ 构件位置 = 所属缝交点（一横一纵，resolver 校验）
  • 🚧 z 向定位 / 标高体系：缝 elevation + 构件 offset.z 求值发射已通（一榀样例出模 NoError）；FU 缝走向 / 全类型接数据待做 [P0]（→ PRD FR-DAT-1/FR-BLD-2，G1）
  • ⬜ 构件朝向 / 旋转（绕 z 轴）——非圆柱构件必需 [P0]（→ PRD FR-BLD-3，G2）

交互层

  • ✅ Web 工作台（标准库 HTTP + 静态前端）
  • ✅ D 输入 → 一键重建模型与图纸
  • ✅ 构件表 / 轴线表实时刷新
  • ✅ three.js STL 预览（CDN，PNG 兜底）
  • ⬜ 关键参数在线编辑（改构件关键参数即时重算尺度并重建） [P0]（V1 目标 2 → PRD FR-UI-2；含 G12 在线数据编辑子集）
  • ⬜ 撤销 / 重做：会话内编辑动作、内存草稿栈、不写盘、不跨重启 [P1]（→ PRD FR-UI-6）
  • 🚧 模型点选查看构件：平面点选 → 单构件面板已通（C 落回 app/static）；3D 拾取待深化 [P0]（V1 目标 2 → PRD FR-UI-1）
  • ⬜ 多构件组合、断面/柱脚编辑 [P1]
  • ⬜ 构建错误分级提示，定位到字段 / 缝编码（→ PRD FR-UI-4，G10）[P1]
  • 🚧 构件筛选（G15）：族图例 + 缝点选筛选联动已通（C 落回）；「导出子集」另行评估（→ PRD FR-UI-3）[P1]
  • ✅ 间数生成柱网（G17）：输入「面阔 X 间，进深 Y 间」生成缝位与檐柱实例——X 间 = X+1 根柱/排；仅奇数间（明间基准）；间宽自明间每向外一间 ×0.8；柱高 = 0.8×明间面阔；缝型分派 2026-09-22 纠偏：CAO 仅外圈檐柱列（面阔两端 CAO_L/Ro + 进深 CAO_Fo/Bo）、内圈分间线=间缝 JIAN、明间中线=非缝基准面 AXIS_X/AXIS_Y、TUAN_0=中槫缝（脊檩定位线）；规律记录于 docs/coding-system.md，实现 bridge/layout.py + POST /api/layout（frame:true 附一榀）；工作台单一「生成」入口（D + 间数 + 明间宽一次提交，生成数据写 build/generated/，不覆盖静态示例；/api/build 静态数据路径保留供 API/测试）
  • ⬜ 整排 pattern 紧凑写法（→ PRD FR-DAT-5，开放问题 1）[P1]
  • ⬜ 节点式 3D 编辑 [P2]（V1 出项，V2+）

导出格式

  • ✅ STL（OpenSCAD 直出 → Blender）
  • ✅ OBJ（OpenSCAD 2026 原生直出；保底 trimesh 转换）
  • ✅ SVG（projection 三视图轮廓 + Python 排版 → Illustrator）
  • ✅ PDF（reportlab 自带中文字体，零系统依赖）
  • 🚧 codegen 扩展：发射 z / 旋转 / 多断面 / 斜椽实例，STL/OBJ/SVG/PDF 全兼容（非只圆柱）——一榀样例已跑通（13 构件 NoError）；条件 include 不破 MVP [P0]（→ PRD FR-BLD-7）
  • ⬜ 模型交付质量（STL/OBJ 水密、无坏面、三角面可控、按构件分组可辨识、引擎导入正确） [P0]（V1 目标 5 → PRD FR-BLD-8 & NFR-6）
  • ⬜ 导出实例可读名（编码可切换 GB 轴线号 / 缝编码 / 中文方位；V1 仅 OBJ 分组、glTF 后续） [P1]（→ PRD FR-BLD-9）
  • ⬜ DXF（OpenSCAD 原生 2D 导出，零成本可加——等 AutoCAD 需求）[P1]

图纸（Phase 1 已对齐 GB/T 50001-2017，详见 docs/drawing-standard.md）

  • ✅ 三视图（第一角投影：正立面图 / 侧立面图 / 平面图）
  • ⬜ 平面（俯视 / 仰视）+ 立面细化 + 剖切符号指向侧样 [P1]（→ PRD FR-DRW-4 / FR-DRW-5）
  • ✅ 图框（a=25 装订边 / c=5 / 对中标志 / 粗实线 b=0.7）
  • ✅ 标题栏（简化版：图名 / 图号 / 比例 / 日期 / 编码体系版本）
  • ✅ 线宽组 b=0.7：粗 0.7 构件轮廓 / 中 0.35 / 细 0.18 定位轴线（单点长画线）
  • ✅ 图名双下划线 + 比例右侧注写 · 字高系列 2.5/3.5/5
  • ✅ 图纸字号标准化（GB/T 50001 字高系列，Phase 1 落地）
  • ⬜ 定位轴线编号圆（双轨：缝编码 id 主键 + gb_no 自动推导——沿 X 字母南起 / 沿 Y 数字西起；决策点 A 已定，见 drawing-standard.md）（→ PRD FR-DRW-3）[P1]
  • ⬜ 尺寸标注（柱间距、柱高、构件定位等自动标注，数值从 resolver 推导）[P0]（V1 目标 6 → PRD FR-DRW-1；毕业最短板）
  • ⬜ 侧样（横剖面图：一榀梁叠檩 + 瓜柱 + 举架；剖切符号 + 断面填充）[P0]（V1 目标 6 → PRD FR-DRW-2）
  • ⬜ 图层管理（轴线 / 边缘 / 标注独立图层）（→ PRD FR-DRW-6）[P1]
  • ⬜ 比例尺可视化（仅自选比例 / 缩微图纸需要，〔6.0.6〕；Phase 1 已移除常显版本）[P2]（V1 出项）
  • ⬜ 隐线消隐（projection 仅出轮廓；后续可评估 Blender Freestyle 或自实现）[P2]（V1 出项）

工程化

  • ✅ 测试：单元（resolver）+ 冒烟（端到端 OpenSCAD 调用）
  • ✅ Makefile 入口（build / serve / test / clean）
  • ✅ 跨平台：macOS OpenSCAD / Python stdlib + reportlab
  • ✅ CI 草稿（GitHub Actions，ubuntu + apt-get install openscad）
  • ⬜ Release 流程（CHANGELOG + git tag + GitHub Releases 附样例产物）（→ PRD FR-ENG-3）[P1]
  • ⬜ 贡献指南 CONTRIBUTING.md [P1]
  • ⬜ 用户手册 / 复现教程（外部研究者端到端复现路径）[P0]（V1 目标 7 → PRD FR-ENG-1，含 Windows / 大屏）
  • ⬜ 数据 schema 版本化（$version 字段 + 冻结流程，对应原毕业条件 2）（→ PRD FR-DAT-4，V1 目标 3）
  • ⬜ 依赖锁定（requirements/pyproject 钉 reportlab/fontTools/trimesh + 记录 OpenSCAD 最低验证版本）（→ PRD FR-ENG-2）[P1]
  • ⬜ 数据表导出（CSV / XLSX + model_spec.json 存档）[P0]（V1 目标 4 → PRD FR-DAT-6）

需求池（已接受 · 待排）

与 PRD 的关系：已纳入 V1 的能力（如屋顶体系 G3→FR-BLD-6、在线编辑 G12→FR-UI-2、构件筛选 G15→FR-UI-3、多项目 G18→FR-UI-5、断面/z/朝向→FR-BLD-1–4、尺寸标注→FR-DRW-1）以 PRD 为准，本处保留原始 G 编号供追溯；G4 斗栱 / G7 材份·斗口 / 瓦作等为 V1 出项。

构件与体系（远期）

💡 柱收分 / 卷杀 / 侧脚：营造法式柱体非等径直圆柱。

💡 屋顶体系：举折/举架曲线 · 椽 · 望板 · 瓦作（G3）——V1 纳入大木部分（椽/连檐/望板，→ PRD FR-BLD-6），瓦作出项。TUAN 缝辅助线是现成切入点。

💡 斗栱（铺作）：栌斗 / 散斗 / 栱 / 昂（G4）——PUZUO 缝的前置构件。V1 出项。

💡 基础 / 柱础 / 台明（G5）。

💡 门窗装修：隔扇 / 槛窗（G6）。

💡 材份制（宋）/ 斗口制（清）：柱径 D 之外的第二套模数语义（G7）。V1 出项（保持单一模数 D 驱动）。

💡 单位制扩展与一键换算（G14）：

  • 输入单位可选（mm / 营造尺 / 公分 / 英寸），用户可自定义「单位 → 公制」比例（如 1 营造尺 = 320mm；历代营造尺实长不同，比例必须开放输入）
  • 单位与比例写入数据文件，与 schema $version（毕业条件 2）同步设计，保证可复现
  • 一键换算语义 = 重定标：已建模项目切换单位/比例后，所有构件尺寸与缝坐标按比例重算，相对位置不变（参数化管线下实现 = 重跑 resolver + codegen，无需网格缩放）
  • 与 G7 材份/斗口制衔接：材份/斗口可作为单位 profile 预设实现

工程与体验

💡 构建缓存 / 性能预算：当前全量重建 3–8s（6 次 OpenSCAD 调用），构件规模上百后需缓存策略（G8 → PRD FR-ENG-5，[P2] 规模触发）。

💡 产物元数据戳：D 值 · 代码版本 · 时间（当前仅 PDF 有日期）（G9）。

💡 错误诊断字段级定位：无效缝编码 / 模数表达式定位到具体字段（G10 → PRD FR-UI-4）。

💡 数据校验：JSON Schema 在交互层上传时实时校验（当前仅文档层说明）。

💡 CITATION.cff / DOI（Zenodo 归档）：学术引用入口（G11 → PRD FR-ENG-4）。

💡 Web 工作台数据编辑：在线增删构件与缝（当前仅 D 可交互）（G12 → PRD FR-UI-2）。前置依赖 T3（XSS 加固）——T3 已完成 ✅（8a0235c，表格/提示改 DOM 构建），注入面前置解除，G12 可排期。

💡 Windows 平台验证：当前仅 macOS 开发验证 + Linux CI（G13 → PRD FR-ENG-5）。

💡 多项目数据管理（G18）[P1]：现状仅「仓库自带一份静态示例 data/」+「CLI --data 指向任意 JSON 目录」+「/api/layout 死写并被覆盖的临时 build/generated/」，没有项目发现、切换、持久化与命名保存（bridge/pipeline.py:31,93；app/server.py:57,124-126）。延续 ADR-0002「数据即事实源」方向补齐：

  • 项目 = 一个带 schema 的 JSON 目录（axes.json + members/*.json），纳入版本控制（独立目录树或独立数据仓），以 --data / 未来 ?project= 定位——可 diff、可复现
  • 生成器可选保存目标：/api/layout 由「永远覆盖 build/generated/」改为「写入指定项目目录」，配套项目列表端点 + 工作台项目选择器
  • 兼容判定随文件走：module.$version（毕业条件 2）+ G14 的 unit/unit_to_mm 一同写入，打开旧项目按声明版本与单位重定标；前置依赖 schema 版本化与 G14 单位决策（开放问题 6）
  • 与 G12（在线数据编辑）天然衔接——G12 的增删改需先落到「当前选中的项目目录」，二者共用同一套项目寻址

💡 翻译：ADR 与其余文档英译（README 已双语，v0.2.1）。

开放问题（待决策）

这些需求级开放问题已在 docs/PRD.md 附录 C 收敛为 O 系列（O1/O5/O7/O10–O16，附建议与影响）；PRD 是决策讨论的主源，本处保留工程视角原文供追溯。

  1. pattern 语法：yanzhu[CAO_Fo, all JIAN] 整排紧凑写法如何与 schema 兼容（ADR-0004 开放项）。两条 CAO 平行无交点——朝向语义更新（ADR-0007）后 CAO_Fo × CAO_Ro即角柱交点，resolver 按 runs 判定已天然支持，无需新代码；剩余难点仅剩pattern 展开的设计问题：枚举谓词（含 except）、ID 自动分配的确定性排序与显式实例冲突规则、schema 增设可选 patterns 数组（oneOf）。（→ PRD O6）
  2. z 向语义：显式标高字段 vs 构件搭接关系 vs 基准面引用，三选一。（→ PRD O3/O4）
  3. 消隐选型：Blender Freestyle vs 自实现 vs 接受轮廓图现状。（V1 出项）
  4. DXF 需求确认：是否已有真实 AutoCAD 用户案例，决定 [P1] 是否提前。（V1 出项）
  5. 首扩展构件：内柱/金柱（复用圆柱，零前置）vs 枋/槫（需先完成 z 向 + 朝向）——已决（2026-09-22）：V1 走「建成整座硬山」路径，直接补 z向/朝向/断面前置并实装梁·桁·枋·椽，放弃「内柱快验凑 ≥3 类」捷径（→ PRD 目标 1、C1–C6）。
  6. 单位换算语义（G14 前置决策）：项目级唯一单位 + 全局比例（推荐，简单可复现）vs 允许字段级混用单位；比例变更默认「重定标」已与用户确认，但历史版本（旧比例的项目文件打开行为）仍需约定。（G14 属 V1.x；→ PRD 附录）
  7. 缝命名统一（G17 遗留）：生成布局中 JIAN 外圈为 Ln/Rn（无 o）、CAO 外圈为 Fo/Bo；静态示例为偶数间（有 JIAN_0）。两套命名是否统一（如 JIAN 外圈也加 o、静态示例重编）待定。（→ PRD O9）

技术债（T 系列）

  1. T1 · write_layout 硬编码 D_mm=300 ✅ 已修复：write_layout(data, out_dir, D_mm=None) 显式传参（缺省写 null），resolve_data 对「数据层与调用参数均无 D」抛明确 ValueError（原为 TypeError）；server 从请求 D 透传；新增 3 例 D 语义测试
  2. T2 · 几何/图纸回归零覆盖 ✅ 已修复（da34e95，测试 26→52 例）：tests/test_codegen.py（构件/轴线逐实例生成、core/ 相对路径、入口与三视图文件集）+ tests/test_sheet.py（图框/图名/标题栏/线宽图元、SVG 合法 XML、PDF 文件头、解析 y 翻转）+ smoke 升级为格式与内容断言（STL solid、OBJ 顶点、图纸含视图名/图号、文件头）
  3. T3 · Web UI innerHTML 注入面 ✅ 已修复（8a0235c）：表格渲染曾全用 innerHTML 拼数据。当前已把 renderAxes / renderMembers（含 Resolved 两版）/ renderFiles / load3D（含 three.js 失败提示）六处数据插值改为 createElement + textContent 构建，杜绝经 HTML 解析的注入路径。纯前端改动，数据流不变；node --check 通过。G12「在线编辑」前置障碍解除。
  4. T4 · Web 服务层零测试 ✅ 已修复（本次，测试 52→63 例）：新增 tests/test_server.py（8 例，后台线程起真实 ThreadingHTTPServer 走完整 HTTP 栈）：端点契约、D 透传、错误分级（偶数间 / 缺 D / 畸形 JSON → 400）、404、路径穿越防御。起因：46baba2 的 T1 修复在 _handle_layout 中引用了尚未赋值的局部变量 D，/api/layout 真实请求 100% 返回 500（工作台「生成」全失效），而 55 例业务测试全绿——HTTP 层当时无回归网。顺带修：do_POST 畸形 JSON 不再冒成 500；缺 D 在落盘前校验（失败请求不写坏 build/generated/）；错误分级统一 _send_error + 500 留服务端日志
  5. T5 · core/lib/units.scad 的 FN 未被引用 ✅ 已修复：该文件从未被任何 .scad 引用，FN = 64 是死常量，column.scad 另写默认值 fn = 64——改 FN 对几何零影响，而 docs/users.md 声称「FN 参数已有」。column.scad 改为 include <../lib/units.scad> + fn = FN；对照实验验证（FN=64 → 252 三角面，FN=8 → 28 三角面）。顺带 README 中英补 fontTools 依赖

版本策略

遵循 SemVer：MVP 迭代期固定 0.x.x（允许小版本内含破坏性变更）。V1（硬山大木构）达成 = 发布 1.0.0（承诺数据格式稳定，升级附迁移说明）。即本文「V1」为产品里程碑，对应 SemVer 1.0.0。

V1 / 1.0.0 的 DoD = docs/PRD.md「V1 七条 DoD」；原四条毕业条件并入其中：

  • 构件类型 ≥3 类 → V1 目标 1（建成面阔三间硬山大木构，编码体系经真实案例校验）
  • 数据 schema 冻结并版本化（$version）→ V1 目标 3
  • ≥1 位外部研究者端到端复现 → V1 目标 7
  • 三视图达可交付 / 出版质量（尺寸标注为最短板）→ V1 目标 6
  • （新增）关键参数可编辑驱动尺度 → V1 目标 2
  • （新增）模型可交付到主流 3D / 引擎（无坏面、三角面可控） → V1 目标 5
  • （新增）数据可交付（结构化 CSV / XLSX + model_spec.json） → V1 目标 4

备注：MVP 曾考虑「走内柱/金柱快验凑 ≥3 类」的低成本路径；V1 已改为「建成整座硬山」，z 向定位与构件朝向（见「位置语义」区）转为 P0 硬前置（开放问题 5 已决）。