commit a4b11c5d6a194ea1c41f0c290acbffaa65d1e377
Author: xujiang <xujiang@boohee.com>
Date:   Thu Dec 11 16:41:29 2025 +0800

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..44581db
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# TierMaster 动态内容分级工具
+
+React + Vite + @dnd-kit 实现的动态分级榜单，支持自定义层级、跨容器拖拽、批量图片/文本添加、配置导入导出与长图截图。UI 采用深色沉浸式风格，底部待分类池吸底展示。
+
+## 快速开始
+- `make init` 安装依赖
+- `make dev` 启动本地开发（默认 5173 端口）
+- `make lint` 运行 ESLint
+- `make test` 运行 Vitest（当前为占位，可按需补充用例）
+- `make build` 构建产物
+
+## 技术栈与规范
+- 前端框架：React + TypeScript + Vite
+- 拖拽：`@dnd-kit/core` + `@dnd-kit/sortable`
+- 状态管理：`zustand`
+- 样式：Tailwind CSS，自定义深色主题色板，字体使用 Space Grotesk
+- I/O：`file-saver`（JSON 导出/图片保存）、`html2canvas`（长图截图）
+- 规范：`.editorconfig` 统一缩进与行宽；ESLint + Prettier 校验；行宽上限 100；推荐使用 `npm run lint` 自检
+
+## 主要功能
+- **层级管理**：添加/重命名/改色、清空、删除（含物品回收池），拖拽重排层级顺序
+- **物品管理**：批量图片上传（自动裁剪为正方形）、文本卡片创建、删除
+- **拖拽交互**：跨层级/池子拖拽，行内排序，拖拽高亮反馈
+- **数据导入导出**：JSON 结构与 `docs/需求文档.md` 定义兼容
+- **长图保存**：忽略底部操作栏，可下载当前榜单图片
+
+## 数据结构
+`TierConfig`（导入导出）：
+- `tiers`: `{ id, label, color }[]`
+- `items`: `{ id, type: 'text'|'image', content, tierId }[]`
+- `itemOrder`: `Record<containerId, string[]>` 维护容器内排序；`pool` 代表待分类池
+
+## 目录
+- `src/App.tsx`：页面布局、顶部工具栏、交互入口
+- `src/components/`：Tier 行、物品卡片、底部池子等 UI
+- `src/state/useTierStore.ts`：zustand 状态与导入/导出/截图逻辑
+- `src/utils/image.ts`：图片读取与正方形裁剪工具
+
+## 后续扩展建议
+- 增加分级色板选择/校验、移动端触控细节优化
+- 为导入/导出增加 schema 校验与版本控制
+- 增补单元测试（拖拽数据迁移、导入合并、色彩循环等）