# ldesign

**Repository Path**: ldesign-v1/ldesign

## Basic Information

- **Project Name**: ldesign
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LDesign

<p align="center">
  <strong>现代化企业级设计系统 - Monorepo + Git Submodule 架构</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/TypeScript-5.7+-blue?logo=typescript" alt="TypeScript">
  <img src="https://img.shields.io/badge/Vue-3.3+-42b883?logo=vue.js" alt="Vue">
  <img src="https://img.shields.io/badge/React-18+-61dafb?logo=react" alt="React">
  <img src="https://img.shields.io/badge/pnpm-9.15+-F69220?logo=pnpm" alt="pnpm">
  <img src="https://img.shields.io/badge/Node-18+-339933?logo=node.js" alt="Node">
</p>

---

## 快速开始

```bash
# 1. 克隆仓库
git clone https://github.com/poly1603/ldesign.git
cd ldesign

# 2. 初始化所有 submodule（并行拉取，优先按 .gitmodules 分支切换）
pnpm bootstrap

# 3. 在新设备检查系统原生构建工具（默认只检查，不修改系统）
pnpm setup:system

# 如提示缺少工具链，再显式执行一次系统安装
pnpm setup:system -- --apply

# 4. 检查 Node/pnpm、锁文件和原生依赖构建环境
pnpm install:check

# 5. 安装依赖
pnpm install:fast

# 6. 开始开发
pnpm dev
```

> **环境要求**: Node.js >= 22.18.0、pnpm >= 10.0.0（推荐使用当前稳定版）。`pnpm setup:system -- --apply`
> 只需在新设备缺少原生工具链时执行一次。请始终提交有效的
> `pnpm-lock.yaml`；锁文件缺失或为空时，`pnpm install` 与 `pnpm install:fast` 都会直接拒绝安装。

---

## 常用命令

### 项目管理

| 命令                     | 说明                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `pnpm hub`               | 统一命令入口（推荐）                                                                             |
| `pnpm bootstrap`         | clone 后初始化所有 submodule，默认显示进度日志，并优先按 `.gitmodules` 分支切换                  |
| `pnpm init`              | 初始化所有 submodule                                                                             |
| `pnpm setup:system`      | 检查系统原生构建工具；加 `-- --apply` 后在支持的平台执行一次安装                                 |
| `pnpm install:check`     | 检查 Node/pnpm 版本和原生依赖构建环境，不修改文件                                                |
| `pnpm install`           | 默认只安装当前项目及必要的 workspace 依赖，不扫描全部项目                                        |
| `pnpm install:workspace` | 显式安装全部 workspace 依赖（等价于 `pnpm install --config.recursive-install=true --recursive`） |
| `pnpm install:fast`      | 推荐的全 workspace 安装入口，默认启用 `prefer-offline`、稳定日志和较低并发                       |
| `pnpm i:fast`            | `install:fast` 的短别名                                                                          |
| `pnpm clean`             | 清理 node_modules + dist                                                                         |
| `pnpm clean:dist`        | 仅清理构建产物                                                                                   |

`pnpm bin:sync` 会扫描 workspace 中所有带 `bin`
的包，补齐包自身和本地依赖缺失的命令 shim。安装依赖后如果某个 CLI 仍提示“不是内部或外部命令”，先运行：

```bash
pnpm bin:sync
```

使用 `pnpm bin:sync -- --check` 可以只检查、不写入文件。

### Submodule 管理

| 命令               | 说明                                                          |
| ------------------ | ------------------------------------------------------------- |
| `pnpm sub:status`  | 查看所有 submodule 状态                                       |
| `pnpm sub:update`  | 更新所有 submodule（会检查远程新增 submodule 并询问是否同步） |
| `pnpm sub:sync`    | 同步 submodule 配置                                           |
| `pnpm sub:device`  | 多设备切换辅助（status / handoff / resume）                   |
| `pnpm sub:handoff` | 当前设备开发完成后，统一提交并推送 submodule + 主仓库         |
| `pnpm sub:resume`  | 切到另一台设备后，先快进主仓库再同步所有 submodule            |
| `pnpm sub:manage`  | 管理 managed submodule（配置/列表/增删改）                    |
| `pnpm sub:add`     | 新增 managed submodule（可联动 Gitee 仓库）                   |
| `pnpm sub:remove`  | 删除 managed submodule（可选同时删除远程仓库）                |
| `pnpm sub:rename`  | 重命名或迁移 managed submodule（路径/远程仓库）               |

> 说明：在网络不可用或鉴权受限环境下，可使用 `pnpm sub:update -- --no-fetch` 仅快进到本地 `origin/*`
> 分支。说明：所有 `pnpm sub:*` 命令均统一走 `tools/git` 的 `ldesign-git submodule ...` 入口。

#### 多设备推荐流程

```bash
# 设备 A：结束开发前
pnpm sub:handoff

# 设备 B：开始开发前
pnpm sub:resume

# 任意设备：先看整体状态
pnpm sub:device -- status
```

#### 统一入口

以后只需要记住一个命令：

```bash
pnpm hub
```

进入后可直接使用上下键选择分组和动作，回车执行，`Backspace` 返回上一级，`Esc` 退出。

常用示例：

```bash
# 子模块：设备 A 收工前统一提交/推送
pnpm hub -- sub handoff

# 子模块：设备 B 开工前恢复同步
pnpm hub -- sub resume

# 开发构建：只构建当前改动工作区
pnpm hub -- work build-changed

# 环境维护：快速安装依赖
pnpm hub -- env install

# 质量检查：lint + 修复
pnpm hub -- check lint-fix
```

### 开发构建

| 命令                  | 说明                                                        |
| --------------------- | ----------------------------------------------------------- |
| `pnpm dev`            | 启动开发服务器                                              |
| `pnpm build`          | 构建所有包                                                  |
| `pnpm build:graph`    | 按 `@composy/*` 内部依赖图分层构建，并输出失败报告          |
| `pnpm build:tools`    | 通过 graph build 构建 `tools/*` 工作区                      |
| `pnpm build:packages` | 通过 graph build 构建 `packages/*` 工作区并清理源码声明产物 |
| `pnpm build:clean`    | 清理后重新构建                                              |
| `pnpm build:parallel` | 按依赖分组并行构建                                          |
| `pnpm build:changed`  | 仅构建当前改动工作区及其下游                                |
| `pnpm release`        | 调用 `@composy/release`，默认 dry-run 规划所有可发布子包       |
| `pnpm release -- --apply --yes` | 按依赖顺序改版本、逐包构建并生成 `CHANGELOG.md`       |
| `pnpm publish:all`    | 在 release 计划基础上调用 `@composy/release` 发布包           |
| `pnpm release -- --apply --yes --publish --commit --git-tag --push` | 完整发布：发布、提交版本与 changelog、打版本标签并推送 |
| `pnpm lint`           | 代码检查                                                    |
| `pnpm lint:fix`       | 自动修复 lint 问题                                          |
| `pnpm test:e2e`       | 运行 Playwright 端到端测试                                  |
| `pnpm doctor`         | 环境诊断（node/pnpm/git 与 submodule 支持）                 |
| `pnpm doctor:ps`      | 兼容别名，转发到统一 TypeScript doctor                      |
| `pnpm ws:list`        | 列出工作区和可用脚本                                        |
| `pnpm dev:list`       | 列出带 dev 脚本的工作区                                     |
| `pnpm build:list`     | 列出带 build 脚本的工作区                                   |
| `pnpm ws:run`         | 按筛选条件批量执行工作区脚本                                |

发布运行会在 `.ldesign/release-runs/<run-id>/` 保存计划、构建边界和发布状态，可使用
`pnpm release -- --resume <run-id> --apply --yes` 从中断处继续。每次成功构建会写入包内的
`.ldesign/build-records/`，供 changelog 确定版本与 Git 时间边界；根脚本只做工作区编排，
真实构建和发布分别回到包自己的 `build` 与 `@composy/release`。

`--commit` 只暂存每个包的 `package.json` 与 `CHANGELOG.md`，并在子模块发生新提交后创建一个仅包含
gitlink 的根仓库汇总提交，不会把无关改动带入 release。`--git-tag` 必须配合 `--commit`，标签格式为
`<package>@<version>`；`--push` 则必须同时给出 `--commit --git-tag`。默认 `pnpm release` 与
`pnpm publish:all` 不执行任何 Git 写操作。`--git-message 'release: {package}@{version}'` 可覆盖默认提交信息。

### 单包开发

```bash
# 进入子包目录开发
cd libraries/chart/examples/vite-demo
pnpm install
pnpm dev

# 或使用 filter
pnpm --filter @composy/chart-core dev
pnpm --filter "@composy/chart-workspace*" build
```

---

## 项目结构

```
ldesign/
├── packages/          # 核心基础包 (18 个)
│   ├── shared/       # 共享工具函数
│   ├── color/        # 颜色处理工具
│   ├── engine/       # 核心引擎
│   ├── http/         # HTTP 客户端
│   ├── router/       # 路由管理
│   ├── store/        # 状态管理
│   ├── i18n/         # 国际化
│   ├── auth/         # 认证授权
│   ├── permission/   # 权限管理
│   ├── cache/        # 缓存管理
│   ├── crypto/       # 加密工具
│   ├── device/       # 设备检测
│   ├── error/        # 错误处理
│   ├── logger/       # 日志系统
│   ├── notification/ # 通知系统
│   ├── size/         # 尺寸工具
│   ├── template/     # 模板引擎
│   └── tracker/      # 埋点追踪
│
├── libraries/        # 功能库 (31 个)
│   ├── chart/        # 图表组件
│   ├── table/        # 表格组件
│   ├── grid/         # 网格布局
│   ├── form/         # 表单组件
│   ├── editor/       # 富文本编辑器
│   ├── code-editor/  # 代码编辑器
│   ├── markdown/     # Markdown 编辑器
│   ├── 3d-viewer/    # 3D 查看器
│   ├── excel/        # Excel 处理
│   ├── pdf/          # PDF 查看器
│   ├── word/         # Word 处理
│   ├── office-document/ # Office 文档处理
│   ├── calendar/     # 日历组件
│   ├── datepicker/   # 日期选择器
│   ├── gantt/        # 甘特图
│   ├── timeline/     # 时间轴
│   ├── flowchart/    # 流程图
│   ├── mindmap/      # 思维导图
│   ├── tree/         # 树形组件
│   ├── map/          # 地图组件
│   ├── video/        # 视频播放器
│   ├── player/       # 媒体播放器
│   ├── cropper/      # 图片裁剪
│   ├── upload/       # 文件上传
│   ├── signature/    # 签名组件
│   ├── qrcode/       # 二维码
│   ├── barcode/      # 条形码
│   ├── lottie/       # Lottie 动画
│   ├── progress/     # 进度条
│   ├── lowcode/      # 低代码平台
│   └── webcomponent/ # Web Components
│
├── tools/            # 开发工具 (33 个)
│   ├── api-generator/   # API 生成器
│   ├── benchmark/       # 性能测试
│   ├── builder/         # 构建工具
│   ├── changelog/       # 变更日志生成器
│   ├── cli/             # 统一聚合 CLI（ldesign）
│   ├── configmate/      # 配置管理
│   ├── deployer/        # 部署工具
│   ├── deps/            # 依赖管理
│   ├── docs-generator/  # 文档生成器
│   ├── env/             # 环境变量管理
│   ├── formatter/       # 代码格式化
│   ├── generator/       # 代码生成器
│   ├── git/             # Git 工具
│   ├── icons/           # 图标资产工具
│   ├── kit/             # 开发套件
│   ├── launcher/        # 项目启动器
│   ├── longpress/       # 文档系统 CLI
│   ├── mock/            # Mock 数据
│   ├── monitor/         # 监控工具
│   ├── performance/     # 性能分析
│   ├── playground/      # 演练场运行时
│   ├── release/         # 发布工具
│   ├── runtime/         # 运行时 helper
│   ├── security/        # 安全检查
│   ├── testing/         # 测试工具
│   ├── tool-server/     # 服务端 helper
│   ├── translator/      # 翻译工具
│   ├── tsup-config/     # 统一 tsup 配置
│   ├── ui/              # UI helper（tool-ui）
│   ├── vscode/          # VS Code 适配
│   ├── webfont/         # 字体资产工具
│   ├── workbench/       # 本地项目工作台（CLI + Web 工作台）
│   └── workspace/       # 工作区管理
│
└── apps/             # 应用示例
    └── app-vue/      # Vue 3 示例应用
```

### 包组织模式

每个主要功能库采用**框架适配器模式**：

```
libraries/chart/
└── packages/
    ├── core/        # @composy/chart-core (框架无关)
    ├── react/       # @composy/chart-react
    ├── vue/         # @composy/chart-vue
    └── lit/         # @composy/chart-lit
```

---

## 模块分类

### 核心基础包 (packages/)

提供底层通用能力，跨框架复用：

- **工具类**: `shared`, `color`, `size`, `crypto`, `device`
- **框架类**: `engine`, `router`, `store`, `i18n`, `template`
- **服务类**: `http`, `cache`, `logger`, `tracker`, `notification`
- **安全类**: `auth`, `permission`, `error`

### 功能库 (libraries/)

面向业务场景的高级组件，支持多框架：

- **数据展示**: `chart`, `table`, `grid`, `gantt`, `timeline`
- **编辑器**: `editor`, `code-editor`, `markdown`
- **文档处理**: `excel`, `pdf`, `word`, `office-document`
- **输入组件**: `form`, `datepicker`, `calendar`, `upload`, `signature`
- **绘图工具**: `flowchart`, `mindmap`, `3d-viewer`
- **媒体组件**: `video`, `player`, `lottie`, `cropper`
- **工具组件**: `qrcode`, `barcode`, `map`, `tree`, `progress`
- **平台类**: `lowcode`, `webcomponent`

### 开发工具 (tools/)

提升开发效率的工具链：

- **构建工具**: `builder`, `launcher`
- **代码工具**: `cli`, `generator`, `formatter`, `translator`, `api-generator`
- **质量工具**: `testing`, `benchmark`, `monitor`, `performance`, `security`
- **发布工具**: `deployer`, `release`, `changelog`, `docs-generator`
- **管理工具**: `git`, `deps`, `workspace`, `vscode`
- **配置工具**: `configmate`, `env`, `mock`, `tsup-config`
- **资产与共享能力**: `icons`, `webfont`, `kit`, `runtime`, `tool-server`, `ui`
- **项目工作台**: `workbench`
- **文档与演练场**: `longpress`, `playground`

> 完整清单以 `ldesign tools list` / `ldesign tools matrix` 为准。

---

## 架构说明

### Submodule = Git 边界

本项目采用 **Monorepo + Git Submodule** 混合架构：

- **Git 管理**: 每个包都是独立的 Git 仓库（Submodule），有独立的历史和权限
- **依赖管理**: pnpm workspace 统一管理所有包的依赖
- **开发模式**: 所有开发都在主仓库中进行

### 关键优势

| 优势            | 说明                                 |
| --------------- | ------------------------------------ |
| ⚡ 自动依赖链接 | 修改任何包，依赖它的包自动使用新版本 |
| 🔄 跨包开发流畅 | 一个命令同时开发多个包               |
| 🌳 Git 灵活性   | 每个包独立版本控制，可设置不同权限   |
| 📦 零配置       | 不需要复杂的脚本和配置               |
| 🎯 标准工作流   | 使用标准的 pnpm monorepo 模式        |

---

## 贡献

欢迎贡献！我们遵循以下原则：

### 贡献指南

1. **Fork 本仓库**
2. **创建功能分支** (`git checkout -b feat/amazing-feature`)
3. **提交修改** (遵循 [Conventional Commits](https://www.conventionalcommits.org/))
4. **推送到分支** (`git push origin feat/amazing-feature`)
5. **发起 Pull Request**

### 提交规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```bash
feat: 添加新功能
fix: 修复 Bug
docs: 文档变更
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建/工具变动
ci: CI 配置变更
```

### Git 工作流

```bash
# 1. 创建分支
git checkout -b feat/new-feature

# 2. 进入 submodule 修改代码
cd packages/color
git checkout -b feat/new-feature

# 3. 提交 submodule 修改
git add .
git commit -m "feat: add new feature"
git push origin feat/new-feature

# 4. 回到主仓库，更新 submodule 引用
cd ../..
git add packages/color
git commit -m "chore: update color submodule"
git push
```

---

## 许可证

MIT License

---

## 相关资源

- **GitHub**: [poly1603/ldesign](https://github.com/poly1603/ldesign)
- **Issues**: [问题追踪](https://github.com/poly1603/ldesign/issues)
- **Discussions**: [社区讨论](https://github.com/poly1603/ldesign/discussions)
- **文档**: 🚧 正在建设中...
- **Playground**: 🚧 正在建设中...

---

## 问题排查

### Submodule 未初始化

```bash
pnpm bootstrap
# 或
pnpm sub:setup
# 或
node --experimental-strip-types scripts/index.ts init --parallel
```

### 依赖安装失败

```bash
pnpm setup:system          # 查看当前设备是否缺少原生工具
pnpm setup:system -- --apply  # 仅在缺少工具时执行一次
pnpm install:check         # 确认版本、锁文件和原生构建工具
pnpm install:fast          # 通过预检后重试
```

`tools/mock` 和 `tools/translator` 需要
`better-sqlite3`。它没有适用于当前平台的预编译包时会自动从源码构建，因此 Linux 需要
`build-essential`，macOS 需要 Xcode Command Line Tools，Windows 需要 Visual Studio Build
Tools 的 C++ 工作负载。不要跳过该依赖的安装脚本，否则这两个工具无法打开本地 SQLite 数据库。
`pnpm setup:system` 默认只报告状态；`-- --apply`
才会执行系统级安装。锁文件是必需文件，丢失时请从 Git 恢复，而不是用一次普通安装重新生成一套版本。

### 构建失败

```bash
pnpm clean:dist      # 清理构建产物
pnpm build           # 重新构建
```

### 查看 Submodule 状态

```bash
pnpm sub:status
```

---

## 当前目录边界

根目录按“可复用程度”和“运行职责”分层：

| 目录 | 存放内容 |
| --- | --- |
| `packages/` | 基础能力、运行时和框架适配器 |
| `libraries/` | 面向用户的完整功能库和领域组件 |
| `apps/` | 可直接运行的产品、应用壳和应用模板包 |
| `tools/` | CLI、构建器、启动器、文档/Playground 工具 |
| `templates/` | 项目起始模板和跨项目脚手架 |
| `docs/examples/` | 不参与运行时构建的 SQL、配置和资料示例 |

当前已完成的归类迁移：

- `apps/playground` → `tools/playground`
- `libraries/doc`（包名 `@composy/longpress`）→ `tools/longpress`
- `apps/miniprogram` → `templates/miniprogram`
- `libraries/database-library-management-system/docs` → `docs/examples/database-library-management-system`

`apps/app-vue` 和 `apps/app-vanilla` 保留在 `apps/`：它们同时承担可运行应用入口和公开模板包入口，是有意保留的应用型特例；`packages/app` 继续只承载框架无关的 `@composy/app-core`。

## FAQ

**为什么选择 Monorepo + Submodule 架构？**

- **Monorepo** 提供统一的开发体验和依赖管理
- **Submodule** 提供独立的版本控制和权限管理

**支持哪些框架？**

Vue 3.3+ / React 18+ / Lit 3+ / Web Components

**如何贡献代码？**

请阅读 [贡献指南](#贡献) 章节。

---

<p align="center">
  Made with ❤️ by LDesign Team
</p>