UI/ARCHITECTURE.md

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/               # 33 个组件 + 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 过全套门禁