# WBBR · AI 前端样式模板工程

WBBR 是一套用于在项目内为 AI 定义、展示和复用前端样式的 React 模板工程。它通过可直接运行的真实页面，向 AI 提供明确的布局、颜色、组件、交互和响应式参考，减少生成页面时的视觉偏差。仓库内的演示内容由本地 JSON 提供，无需后端即可作为 AI 编码的前端样式基准。

## 项目特点

- 纯前端运行：无需数据库、接口服务或登录系统
- 模板集中导航：首页统一展示并搜索全部页面模板
- 本地模拟数据：业务数据集中保存在 `app/data` 目录
- 独立页面路由：每个模板可单独浏览、修改和复用
- 完整交互演示：包含拖拽、筛选、编辑、高亮、预览和本地保存
- 响应式布局：兼容桌面端、平板和移动端尺寸
- 易于接入后端：保留现有组件，只需替换 JSON 数据读取方式
- 面向 AI 协作：通过完整页面和组件实例明确项目期望的前端视觉语言

## 在 AI 开发中的用途

- 让 AI 优先复用本工程中的页面结构、组件形态和 CSS 规则
- 为新页面提供可定位的路由参考，而不是仅依赖文字描述样式
- 统一后台、内容页和可视化页面的视觉密度与交互方式
- 使用本地 JSON 快速验证 AI 生成的页面，不依赖后端开发进度
- 将确认后的新模板继续沉淀进主页导航，形成项目样式资产库

## 模板导航

| 路由 | 模板 | 主要功能 |
| --- | --- | --- |
| `/` | 模板中心 | 分类导航、模板搜索、精选模板入口 |
| `/admin` | 后台组件总览 | 多级菜单、标签、按钮、图文列表、定时任务 |
| `/approval` | 审批流程设计 | 类飞书流程图、节点添加、条件分支、节点配置、JSON 预览 |
| `/worklist` | 多级工作列表 | 项目、里程碑、任务和子任务树形表格 |
| `/kanban` | 泳道任务看板 | 卡片跨泳道拖拽、状态更新、任务卡片 |
| `/repeatable-form` | 可重复表单 | 动态添加表单组、图片列表、文件列表和本地保存 |
| `/simple-list` | 简单列表 | 搜索、标签筛选、分页和批量操作 |
| `/markdown` | Markdown 编辑器 | 文档编辑、实时预览和浏览器本地保存 |
| `/anime` | 动漫作品详情 | 作品资料、剧集、评论及衍生商品展示 |
| `/character` | 角色详情 | 角色标签、关系、档案与剧情轨迹 |
| `/image-host` | 响应式图床 | 瀑布流、图集、灰色蒙版、延时大图预览和详情页 |
| `/media-player` | 视频播放器 | 播放控制、进度、倍速、播放列表、画中画与全屏 |
| `/music-player` | 音乐播放器 | 同步歌词、可拖动歌单和播放模式 |
| `/calendar` | 时令事件日历 | 连续事件、日期高亮、水果与海鲜应季期 |
| `/produce-map` | 全球产物地图 | 国家和一级行政区高亮、河北省市级下钻、产物详情 |
| `/bigscreen` | 数据大屏 | 实时指标、经营数据和趋势图表展示 |
| `/stargraph` | 星空关系网络 | 节点添加、直线关联、悬停详情和 JSON 导入导出 |
| `/icons` | 网页图标库 | 图标分类、搜索、预览与代码复制 |

## 重点功能

### 审批流程设计器

- 审批、条件分支和抄送节点
- 点击或拖入方式添加节点
- 单人审批、或签和会签配置
- 审批人、表单权限及高级规则配置
- 流程校验、模拟预览和 JSON 查看
- 自动保存与浏览器本地发布状态

### 多级工作列表

- 项目 → 里程碑 → 任务 → 子任务四级结构
- 单项展开、全部展开和全部收起
- 关键词、状态和优先级组合筛选
- 多选、全选及批量操作
- 工作项详情与状态编辑

### 全球产物地图

- 中国、日本、美国、俄罗斯等国家和地区地图
- 一级行政区点击、悬停和高亮展示
- 美国本土与阿拉斯加、夏威夷分区布局
- 俄罗斯国土跨度适配投影
- 河北省下钻至 11 个地级市
- 省市级代表产物、产季和产区说明

## 技术栈

- React 19
- Next.js 16 页面结构
- vinext / Vite 8 构建与运行
- TypeScript 5
- CSS Modules
- D3 Geo 地理数据投影
- Cloudflare Workers 兼容构建
- JSON 和 `localStorage` 本地数据模拟

## 快速启动

运行环境需要 Node.js `>= 22.13.0`。

### Windows 一键启动

直接双击仓库根目录中的：

```text
run.cmd
```

也可以在 PowerShell 中运行：

```powershell
Set-Location "D:\RECS-WEB-MODLE-REACT"
npm run start:local
```

该命令会自动处理 Windows 静态资源路径兼容问题、执行生产构建，并在以下地址启动完整项目：

```text
http://localhost:3000/
```

按 `Ctrl + C` 可以停止服务。

### 常规开发

```bash
npm install
npm run dev -- --port 3000
```

### 构建与检查

```bash
npm run build
npm run lint
npm test
```

## 项目结构

```text
WBBR/
├─ app/
│  ├─ TemplateHub.tsx        # 模板主导航页
│  ├─ admin/                 # 后台组件模板
│  ├─ approval/              # 审批流程设计器
│  ├─ worklist/              # 多级工作列表
│  ├─ produce-map/           # 全球产物地图及河北市级下钻
│  ├─ media-player/          # 视频播放器
│  ├─ music-player/          # 音乐播放器
│  ├─ data/                  # 页面演示 JSON 数据
│  └─ ...                    # 其他独立模板页面
├─ public/
│  ├─ maps/                  # 国家、省市行政区 GeoJSON
│  ├─ anime/                 # 作品与内容示例图片
│  └─ seasonal/              # 日历及应季素材
├─ scripts/
│  └─ start-local.mjs        # Windows 一键构建启动脚本
├─ tests/                    # 页面构建结果检查
├─ run.cmd                   # Windows 本地一键启动入口
├─ 启动项目.cmd              # 中文名称启动入口
├─ package.json
└─ README.md
```

## 数据文件

| 文件 | 用途 |
| --- | --- |
| `app/data/mock-data.json` | 后台概览、组件及定时任务 |
| `app/data/approval-flow.json` | 审批节点、条件和流程配置 |
| `app/data/work-list.json` | 多级工作项及层级关系 |
| `app/data/kanban-board.json` | 泳道和任务卡片 |
| `app/data/repeatable-forms.json` | 可重复表单内容 |
| `app/data/media-player.json` | 视频、音乐和播放列表 |
| `app/data/seasonal-calendar.json` | 日历事件和应季信息 |
| `app/data/produce-map.json` | 国家、行政区和代表产物 |
| `app/data/star-graph.json` | 星空关系节点和连线 |
| `app/data/web-icons.json` | 网页图标分类与代码 |

地图边界文件位于 `public/maps`，其中包括国家一级行政区数据和河北省市级行政区示例数据。

## 数据保存方式

本项目暂时不依赖后端：

- 初始演示内容来自本地 JSON
- 页面编辑结果按功能保存在浏览器 `localStorage`
- 清除浏览器站点数据后，页面会恢复到 JSON 初始状态
- `.openai/hosting.json` 中的 D1 和 R2 均为 `null`

## 接入真实接口

接入后端时建议保留页面组件和类型定义，只替换数据层：

1. 将 JSON 导入替换为 `fetch` 或项目统一请求客户端。
2. 将 `localStorage` 保存逻辑替换为新增、修改和删除接口。
3. 为加载、失败和空数据状态接入真实返回结果。
4. 保持现有数据字段，或在接口层增加字段转换函数。

## 适用场景

- 后台管理系统原型
- 产品需求与交互演示
- 前端页面模板选型
- 无后端条件下的业务验证
- React / TypeScript 页面开发参考
- 新项目的管理端或内容端基础工程