create-medical-document

v0.1.5

Published

2 months ago

Scaffold a medical document framework project.

0High
0Medium
0Low

changlei18

create scaffold medical vite electron

medical_document_framework

本仓库发布的是一个脚手架包（create-medical-document），用于：

创建新的业务项目
对已创建的项目生成“新版模板快照”（用于手动 diff/合并）

创建项目（create）

在你希望放置项目的目录执行（会创建一个新文件夹）：

npx create-medical-document@latest --name <project-name>

常用参数：

--yes：跳过交互提示（全部用默认值）
--electron：生成 Electron 项目（默认）
--no-electron：生成纯 Web 项目（会移除 electron/ 目录及相关脚本/依赖）

示例：

# 生成 Web 项目
npx create-medical-document@latest --name med-doc-web --no-electron --yes

# 生成 Electron 项目
npx create-medical-document@latest --name med-doc-electron --electron --yes

创建完成后，项目根目录会带有一个 .scaffold-meta.json 用于追溯生成信息。

升级既有项目（upgrade，生成模板快照）

当你已经基于旧版本脚手架创建并开发了业务项目，但脚手架包发布了新版本时，推荐使用 upgrade 生成快照 的方式升级：

⚠️ 升级前请先备份数据（建议先提交当前代码，或创建备份分支）。

npx create-medical-document@latest upgrade

防忘记用法（推荐）：

npm run upgrade

说明：当前模板已内置该脚本，等价于：

npx create-medical-document@latest upgrade --target .

.scaffold-upgrade/template-<version>-<timestamp>/

用 diff 工具对比并手动合并你需要的变更：

git diff --no-index . .scaffold-upgrade/template-*/ | cat

说明：

upgrade 默认 不会修改 你已有项目的任何文件，只会新增快照目录。
可选参数：

# 指定目标项目与输出目录，并允许覆盖输出目录
npx create-medical-document@latest upgrade --target . --output .scaffold-upgrade/snapshot --force

# 仅导出指定目录（逗号分隔）
npx create-medical-document@latest upgrade --target . --include src,doc

# 排除指定目录/文件（逗号分隔）
npx create-medical-document@latest upgrade --target . --exclude src/creator,README.md

升级过滤配置文件：.scaffold-upgrade.config.json（位于目标项目根目录，默认自动读取）。
配置示例：

{
  "upgrade": {
    "include": ["src", "doc"],
    "exclude": ["src/creator", "README.md"]
  }
}

include/exclude 都是“项目相对路径前缀匹配”；exclude 优先级高于 include。
命令行参数 --include / --exclude 会覆盖配置文件中的同名字段。
如需自定义配置文件路径，可使用：

npx create-medical-document@latest upgrade --target . --filter-config ./custom-upgrade-filter.json

发布到 npm（防忘记）

# 先预览将要发布的内容（推荐）
npm run publish:npm:dry

# 正式发布
npm run publish:npm

说明：

本项目已配置 publishConfig.access=public，脚本里也显式带了 --access public。
发布前请先更新 package.json 里的 version，避免同版本重复发布失败。

配置入口说明（src/config.ts）

业务项目的运行入口配置在 src/config.ts，导出 config: AppConfig。它主要用来描述：

1) 画布/适配相关

designWidth / designHeight：设计稿尺寸（用于内部缩放/布局基准）。
minWidth / minHeight（可选）：约束最小可用尺寸（当前示例里注释掉了）。

2) 调试相关

debug：是否开启调试能力（例如调试 overlay、指标等，具体由工程内实现决定）。
debugMode：调试模式（当前示例为 "device"）。

3) 资源预热（resourcePreload）

用于控制启动时的资源预加载策略：

enabled：是否启用预加载。
mode：预加载模式（示例为 "auto"）。
exclude.prefixes：跳过特定前缀的资源 URL（示例排除了 /creator_uploads/ 与 project://）。
concurrency：并发数。
timeoutMs：单个资源预加载超时。

4) 页面/Stage 注册（stages）

stages 是一个 Stage 列表，每个 Stage 至少包含：

id：Stage 唯一标识（必须唯一）
title：标题
component：对应的 React 组件

示例里使用 ensureUniqueStageIds(...) 做了一次唯一性保障。

5) 菜单结构（menu）

menu: AppMenuItem[] 用于描述左侧/顶部等菜单树（具体渲染由 UI 层实现决定）。常见字段：

id：菜单项 id
label：展示文本
children：子菜单（树形结构）

6) UI 扩展（ui）

ui 用于注册额外 UI（示例为空数组）。具体可用项以 AppConfig 类型定义为准。

运行时动态编排 API（快速上手）

项目内已提供一套运行时 API，可以在程序运行过程中动态管理 stages 和 menu（内存态生效，不改写 src/config.ts）：

单例入口：src/runtime/runtimePlan.ts
完整类型与实现：src/runtime/menuStagePlan.ts

1) 基础调用

import { runtimePlan } from "@/runtime";

// 新增 stage
await runtimePlan.addStage({
  stage: { id: "s2", title: "随访", component: FollowupStage },
});

// 新增一级菜单并绑定到 stage
await runtimePlan.addMenuItem({
  item: { id: "m-followup", label: "随访", stageId: "s2" },
});

2) 常用操作

import { runtimePlan } from "@/runtime";

await runtimePlan.updateMenuItem({
  id: "m-followup",
  patch: { label: "随访管理" },
});

await runtimePlan.bindMenuToStage({
  id: "m-followup",
  stageId: "s2",
});

await runtimePlan.moveStage({ id: "s2", index: 0 });

3) 串行事务（推荐）

import { runtimePlan } from "@/runtime";

await runtimePlan.runInTransaction("init-followup", (tx) => {
  tx.addStage({ stage: { id: "s2", title: "随访", component: FollowupStage } });
  tx.addMenuItem({ item: { id: "m-followup", label: "随访", stageId: "s2" } });
});

4) 订阅变化

import { runtimePlan } from "@/runtime";

const unsubscribe = runtimePlan.subscribe((snapshot, patch) => {
  console.log("patch:", patch.type, patch.payload);
  console.log("stages:", snapshot.stages.length, "menu:", snapshot.menu.length);
});

// 结束监听
unsubscribe();

详细 API（参数、错误码、联动策略）请看：doc/runtime-api.md。