# boardform

**Repository Path**: chging/boardform

## Basic Information

- **Project Name**: boardform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BoardForm 工程外壳生成平台

BoardForm 是面向机械结构设计的本地优先 Web 工作台：从创建工程草稿开始，登记几何输入，确认三维几何，维护产品要求与方案决策，最后由用户明确触发 ForgeCAD 源码和工程数据生成。

## 文档

- [功能手册](功能手册.md)：逐项列出产品功能、数据规则、操作方法与当前边界。
- [调试与自动化测试手册](调试手册.md)：每个 BF 功能编号对应测试代码、选择器、步骤和预期结果。

## 本次版本重点

- 首页不再预置“工业电机控制器外壳”，首次进入从创建工程开始。
- 工程草稿支持新建、打开、重命名、删除和浏览器本机保存。
- 模板会创建一个独立新工程，工程名来自模板名，不覆盖当前草稿。
- 产品要求与方案决策均可新增、编辑、删除；制造要求保持必选。
- 动态生成并下载 `product_requirements.yaml`、`enclosure_design_spec.json` 和 `board_data.json`。
- 源码步骤先显示生成确认面板，只有点击“开始生成”后才显示输出文件。
- 几何确认改为可旋转、平移、缩放和两点测量的交互式 3D PCB 模型。
- 模型连接支持 API Key、模型调用名称、自定义端点和完整 CRUD；API Key 按登录账号使用 AES-GCM 加密持久保存；内置 DeepSeek、通义千问、GLM、Kimi、豆包、千帆、硅基流动、OpenAI、Anthropic、Gemini 等预设。
- 新增 D1 账号密码体系：内置管理员、HttpOnly 会话、密码哈希、修改密码、管理员新增和停用账号。
- 统一 BoardForm 标志、森林绿/工程橙色彩、字体与全局按钮 hover/active 动效。
- 桌面、平板和手机布局适配。

## 产品方案

流程遵循“确定性数据优先、模型辅助决策、人工闸门放行”：

1. 创建独立工程草稿。
2. 登记 STEP/STP/ZIP/DXF 主输入和补充资料。
3. 在 3D 视图中检查几何并人工确认。
4. 维护环境、散热、振动、连接、维护和制造要求。
5. 维护结构参数与可追溯方案决策。
6. 用户明确点击生成，输出 ForgeCAD 分件源码及 YAML/JSON 派生文件。
7. 下载单文件或完整 JSON 工程包。

## 本地运行

要求 Node.js 22.13 或更高版本。

```bash
npm install
cp .dev.vars.example .dev.vars
# 将 .dev.vars 中的 MODEL_KEY_ENCRYPTION_SECRET 改为至少 32 位随机值
npm run dev
```

开发地址以终端输出为准，通常为 `http://localhost:5173`。

质量检查：

```bash
npm run lint
npm run build
npm test
```

| 命令 | 用途 |
| --- | --- |
| `npm run dev` | 启动开发服务 |
| `npm run build` | 构建 Vinext/Cloudflare Worker 产物 |
| `npm run start` | 启动生产构建 |
| `npm run lint` | ESLint 静态检查 |
| `npm test` | 生产构建后执行全部 Node 自动化测试 |

## 初始管理员

首次部署会自动创建管理员：

- 账号：`admin`
- 初始密码：`Admin@123456`

首次登录后页面会提示立即修改密码。密码使用 PBKDF2-SHA256 派生哈希保存，登录会话使用 HttpOnly、SameSite=Strict Cookie。

## 数据保存与下载

工程草稿、非敏感模型信息和系统设置保存在当前浏览器；账号、密码哈希、登录会话以及加密后的模型 API Key 保存在 D1 数据库。API Key 使用服务端 `MODEL_KEY_ENCRYPTION_SECRET` 通过 AES-GCM 加密，按登录账号隔离；页面只读取“是否已保存”，不会取回或显示明文，也不会写入 Git、工程包或服务端日志。

可下载文件：

- `bottom-shell.forge.js`
- `top-cover.forge.js`
- `right-panel.forge.js`
- `gasket-reference.forge.js`
- `board_data.json`
- `product_requirements.yaml`
- `enclosure_design_spec.json`
- `<工程名>-完整工程.zip` 完整工程包（包含上述 4 个 `.forge.js` 和 3 个派生文件）

YAML 和设计规格 JSON 会根据当前工程名、启用要求、结构参数与方案决策实时重建。编辑工程后，旧生成状态自动失效，需要重新点击生成。

## 目录结构

```text
BoardForm-web-project/
├── app/
│   ├── page.tsx                 # 产品状态和全部业务交互
│   ├── InteractiveBoard3D.tsx   # 交互式 3D/测量画布
│   ├── GeneratedEnclosure3D.tsx # 生成源码同参数 3D 预览
│   ├── forgecad-source.mjs      # ForgeCAD 运行时兼容检查
│   ├── forgecad-templates.mjs   # 已验证的确定性源码模板
│   ├── zip-package.mjs          # 浏览器端标准 ZIP 工程包
│   ├── globals.css              # 品牌视觉与响应式样式
│   ├── layout.tsx               # 元数据
│   └── api/                     # D1 鉴权、模型代理与测试连接
├── db/                          # D1 表结构
├── drizzle/                     # D1 迁移文件
├── tests/
│   ├── source-contract.test.mjs # BF 功能契约测试
│   ├── zip-package.test.mjs     # ZIP 目录与文件名测试
│   └── rendered-html.test.mjs   # 构建产物 SSR 测试
├── 功能手册.md
├── 调试手册.md
├── worker/                      # Cloudflare Worker 入口
├── .openai/hosting.json         # Sites 部署配置
└── package.json
```

## 当前边界

这是可操作的产品原型，不是生产 CAD 求解服务：

- 主文件当前只登记文件名，不解析或上传 CAD 内容。
- 3D PCB 是交互演示模型，测量值来自当前屏幕投影比例。
- 配置默认模型和 API Key 后，“生成”会通过同源后端代理真实调用模型；未配置模型时使用本地确定性模板。
- “测试连接”会发送一次极短的真实模型请求，验证 Key、模型名和端点；端点支持基础地址、完整 `/chat/completions` 和完整 `/responses`，并自动选择对应协议。额度、计费、Key、模型权限和限流错误会以中文提示。真正的源码生成发生在“开始生成”。API Key 由服务端在调用时解密使用，明文不返回浏览器。
- 源码预览默认不换行，代码区始终提供横向和纵向滚动条；也可切换自动换行。
- 生成端禁止 JSCAD 外部模块以及 `cylinder`、`box` 等 ForgeCAD 运行时名称冲突，首次输出不兼容时会自动重写一次；旧的不兼容源码会被拦截并回退到已验证模板。
- STEP 05 可切换“3D 预览”并下载 PNG。该视图与源码共用参数，但不是 ForgeCAD 几何内核执行结果；当前 Cloudflare Sites 运行时不能启动本机 ForgeCAD CLI。真正的自动 ForgeCAD 执行/渲染需要单独部署具备 ForgeCAD Enterprise 授权的渲染服务。
- IP 等级、热设计、抗振和制造结论仍需合格工程师与实物验证。

## 生产化建议

后续可继续接入 STEP/Gerber 解析器、规则引擎、ForgeCAD Enterprise 渲染服务及工程草稿跨设备同步。生产环境必须长期保管 `MODEL_KEY_ENCRYPTION_SECRET`；若更换该主密钥，已加密的 API Key 将无法解密，需要用户重新填写。

## License

[Apache License 2.0](LICENSE)