20261007220117

code/g3soft-libs/README.md

@@ -0,0 +1,89 @@
+# g3soft-frontend
+
+G3Soft 前端技术基础设施：**自研 Vue 3 组件库** + **Docus 文档站**，pnpm monorepo 管理。
+
+## 目录结构
+
+```
+g3soft-frontend/
+├── pnpm-workspace.yaml        # workspace 声明 + catalog 统一版本 + 构建脚本白名单
+├── packages/
+│   ├── ui/                    # 组件库（发布到 npm 私库）
+│   │   ├── src/button/        # 一组件一目录
+│   │   └── vite.config.ts     # 产出 ESM + 类型声明
+│   └── tokens/                # 设计变量，组件库与文档站共用
+├── docs/                      # 文档站（private，不发布）
+│   ├── nuxt.config.ts         # Docus Layer + alias 直连 packages 源码
+│   ├── content/               # Markdown 内容（路由与导航自动生成）
+│   ├── examples/              # 可运行示例，按组件分目录
+│   ├── data/api/              # gen:api 生成的 API 数据（不要手改）
+│   └── app/components/content # Demo.vue / ApiTable.vue（可在 md 中直接使用）
+└── scripts/gen-api.mjs        # 从组件源码生成 API 表格数据
+```
+
+## 环境要求
+
+- Node.js >= 20.19
+- pnpm 11（`better-sqlite3` 是 Docus 全文搜索依赖的原生模块，已在 `allowBuilds` 中放行）
+
+## 安装
+
+```bash
+pnpm install
+```
+
+## 开发
+
+```bash
+pnpm dev
+```
+
+启动文档站（默认 http://localhost:3000）。组件源码通过 alias 直连，改 `packages/ui` 会即时热更。
+
+## 构建
+
+```bash
+pnpm gen:api      # 从组件源码重新生成 API 数据（改了 props/events/slots 后必跑）
+pnpm build        # 构建 packages/*（组件库产出 dist）
+pnpm build:docs   # 构建文档站静态文件
+```
+
+文档站静态产物在 `docs/.output/public`，可直接部署到任意静态托管。
+
+### 部署到子路径
+
+文档站支持挂载到子路径，构建时通过环境变量指定：
+
+```bash
+DOCS_BASE_URL=/docs/ pnpm build:docs
+```
+
+## 发布组件包
+
+组件库走 changesets 管理版本：
+
+```bash
+pnpm changeset        # 记录本次改动
+pnpm version          # 生成版本号与 CHANGELOG
+pnpm release          # 构建并发布到私库
+```
+
+`packages/ui` 的 `prepublishOnly` 会执行 `publint` 校验包结构（`exports`、`files` 是否自洽）。
+
+## 两条链路为什么互不干扰
+
+| | 文档站 | 组件包 |
+|---|---|---|
+| 是否发布 | 否（`private: true`） | 是（npm 私库） |
+| 版本管理 | 无 | changesets（已 `ignore: ["@g3soft/docs"]`） |
+| 构建命令 | `pnpm build:docs` | `pnpm build` |
+| 产物 | `docs/.output/public`（静态） | `packages/ui/dist`（ESM + d.ts） |
+| 依赖边界 | Docus / Nuxt / Tailwind 只在 `docs` 包 | 只有 `vue`(peer) 与 `@g3soft/tokens` |
+
+关键点：Nuxt 相关的依赖**只出现在 `docs/package.json`**，组件库的依赖树里没有任何文档站的东西；changesets 的 `ignore` 保证打 tag 发版时不会带上文档站。
+
+## 约定
+
+- 组件样式**不写 `scoped`**，用 `g3-` 前缀 + BEM，颜色尺寸一律引用 `--g3-*` 变量。
+- API 表格由源码生成，**禁止手写**；改了组件记得跑 `pnpm gen:api`。
+- 示例放 `docs/examples/<组件名>/<示例名>.vue`，在 md 中用 `::demo{name="<组件名>/<示例名>"}` 引用。