HIsheR
69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
# ARCHITECTURE.md - 项目结构规范
|
||
|
||
分层架构 + 目录结构 + 依赖方向的唯一权威定义。目录调整必须先改本文件再动代码。
|
||
|
||
## 分层模型（依赖方向单向，禁止反向）
|
||
|
||
```
|
||
apps/* 应用层：可依赖任何 packages
|
||
↓
|
||
skin/* 皮肤层：DOM 渲染，可依赖 core/* + design/tokens
|
||
↓
|
||
core/* 逻辑层：框架无关 headless，可依赖 core 兄弟包 + design/tokens（约定级）
|
||
↓
|
||
design/* 资产层：设计令牌，不依赖任何包
|
||
|
||
tools/* 工程层：只在构建期读各包 ua.manifest.json / tokens.json，
|
||
不 import 任何运行时代码
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
ui-arch-mvp/
|
||
├── apps/
|
||
│ ├── demo/ # @ui-arch/demo 演示应用（private，esbuild 打单文件）
|
||
│ │ ├── main.ts # 入口
|
||
│ │ ├── build.mjs # 打包脚本
|
||
│ │ └── dist/demo.html # 产物（gitignore）
|
||
│ └── docs/ # 文档站（纯产物，由 ua docs 生成）
|
||
│ ├── index.html # 人类版文档（含演示 iframe）
|
||
│ └── demo.html # ua docs 自动从 apps/demo/dist/ 拷贝的演示页副本
|
||
├── packages/
|
||
│ ├── core/ # 逻辑层（headless，可发布）
|
||
│ │ ├── table-core/ # 表格状态内核
|
||
│ │ └── frame/ # 信号 + hyperscript 微框架
|
||
│ ├── skin/ # 皮肤层（DOM 组件，可发布）
|
||
│ │ └── ui/ # 34 个组件 + ui.css
|
||
│ ├── design/ # 资产层（可发布）
|
||
│ │ └── tokens/ # --ua-* 设计令牌
|
||
│ └── tools/ # 工程层（private，不发布）
|
||
│ └── cli/ # ua 命令行 + MCP 注册表服务
|
||
├── scripts/ # 工程脚本：gitea.mjs（git 推送封装）、gitea-api.mjs（Gitea REST API）
|
||
├── ARCHITECTURE.md # 本文件：结构规范
|
||
├── AGENTS.md # Agent 接入手册（兼项目入口文档）
|
||
├── CODING.md # 编码规范
|
||
├── COMMITTING.md # 提交信息规范（commit-lint 机器校验）
|
||
├── ITERATION.md # 无人值守自我迭代协议（自动化 Agent 执行）
|
||
├── pnpm-workspace.yaml # pnpm 工作区定义
|
||
├── pnpm-lock.yaml # 依赖锁定（入库，保证依赖树可复现）
|
||
├── llms-full.txt # Agent 全量文档（ua docs 生成）
|
||
└── .ua/ # 迭代元数据
|
||
├── index.json # 注册表索引（ua index 生成，提交入库）
|
||
├── backlog.json # 迭代待办清单（open/done）
|
||
└── iterations.log # 每轮迭代留痕（lint-iterations 机器校验）
|
||
```
|
||
|
||
## 包规范（每包强制）
|
||
|
||
1. **package.json**：`main`/`types`/`exports` 一律指向 `dist/`（纯资产包如 tokens 除外）；依赖必须显式声明，工作区内用 `workspace:*`；不发布的包加 `"private": true`
|
||
2. **tsconfig**：一律 `extends` 根目录 `tsconfig.base.json`，只写差异项；浏览器包覆盖 `module: ESNext + moduleResolution: Bundler`
|
||
3. **ua.manifest.json**：可发布包必须有（否则不进注册表）；`type` 字段枚举：`headless-core` / `skin-dom` / `design-tokens` / `tooling`。豁免：`tools/*` 与 `apps/*` 为工程/应用包，不进组件注册表，可不带 manifest
|
||
4. **产物**：构建产物只进包内 `dist/`（或 `apps/demo/dist/`），源码与产物永不混放；`dist/` 一律 gitignore
|
||
|
||
## 新增包流程
|
||
|
||
1. 按`分层模型`确定归属目录（逻辑→core，渲染→skin，令牌/图标→design，脚本→tools）
|
||
2. 建目录 + package.json + tsconfig.json（extends base）+ ua.manifest.json
|
||
3. `npm run index` 刷新注册表，`npm run check` 过全套门禁
|