# 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/               # 15 个组件 + ui.css
│   ├── design/               # 资产层（可发布）
│   │   └── tokens/           # --ua-* 设计令牌
│   └── tools/                # 工程层（private，不发布）
│       └── cli/              # ua 命令行 + MCP 注册表服务
├── ARCHITECTURE.md           # 本文件：结构规范
├── AGENTS.md                 # Agent 接入手册（兼项目入口文档）
├── CODING.md                 # 编码规范
├── llms-full.txt             # Agent 全量文档（ua docs 生成）
└── .ua/index.json + llms.txt # 注册表索引（ua index 生成，提交入库）
```

## 包规范（每包强制）

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` 过全套门禁