docs: rewrite README with project overview and Capacitor build flow

Replace the default Vite template README with project-specific docs: tech stack, dev/build/sync scripts, the dist-based Capacitor packaging flow (build before cap sync), project structure, and the dev-only home-layout writer plugin. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 11:25:04 +08:00
parent 4ad8e7cbec
commit 8f164fd04e
1 changed files with 88 additions and 58 deletions
--- a/vtubermini/README.md
+++ b/vtubermini/README.md
@@ -1,73 +1,103 @@
-# React + TypeScript + Vite
+# VTuber Mini

-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+单个虚拟主播的粉丝陪伴 App。粉丝每天回到这个私密的「冷蓝色粉丝空间」照料主题宠物、抽卡收集、查看纪念日、兑换创作者周边。

-Currently, two official plugins are available:
+本仓库是该 App 的 **前端工程**:一个 React + Vite 构建的单页应用,通过 **Capacitor** 打包为原生 Android App,为 App 提供**本地 H5 界面**(界面随包内置、离线运行,不依赖在线服务器)。

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+> ⚠️ **核心约定**:Capacitor 加载的是 `dist/` 目录里的构建产物(`capacitor.config.ts` 中 `webDir: 'dist'`)。
+> **每次同步到原生工程 / 打包前,必须先 `npm run build`**,否则原生壳里装的是上一次(甚至为空)的旧界面。

-## React Compiler
+---

-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## 技术栈

-## Expanding the ESLint configuration
+| 领域 | 选型 |
+| --- | --- |
+| 框架 | React 19 + TypeScript |
+| 构建 | Vite 8 |
+| 样式 | Tailwind CSS 4(`@tailwindcss/vite`) |
+| 图标 | lucide-react |
+| 原生封装 | Capacitor 8(目前仅 Android 平台) |
+| 代码规范 | ESLint 10 |

-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+## 环境要求

-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+- **Node.js ≥ 20.19**(Vite 8 要求,推荐 LTS)
+- **npm**(项目脚本以 npm 为准)
+- 打包 Android 还需:**JDK 17**、**Android SDK**、Android Studio(可用 `npm run check:android` 自检本机环境)

-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+## 快速开始

-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器(默认 http://localhost:5176,监听 0.0.0.0,可局域网/真机调试)
+npm run dev
 ```

-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+## 构建与打包到 Android

-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+H5 → 原生的链路是:**`build` 生成 `dist/` → `cap sync` 把 `dist/` 同步进 `android/` 工程 → Android Studio / Gradle 打 APK**。

-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+# 1) 构建 H5(类型检查 + Vite 打包,输出到 dist/)
+npm run build
+
+# 2) 把 dist/ 同步进 Android 原生工程
+npm run cap:sync          # 等价于 npx cap sync android
+
+# —— 或者一步到位(先 build 再 sync)——
+npm run android:sync
 ```
+
+同步完成后,用 Android Studio 打开 `android/` 目录构建并运行,或用 Gradle 直接打包 APK。
+
+> 再次提醒:**改了任何前端代码后,务必重新 `npm run build`(或直接 `npm run android:sync`)**,再去构建 APK。`cap sync` 本身不会触发前端构建。
+
+## 项目结构
+
+```
+vtubermini/
+├─ src/
+│  ├─ App.tsx / main.tsx / index.css   # 应用入口与全局样式
+│  ├─ pages/                           # 页面
+│  ├─ components/                      # 业务组件,按功能域划分:
+│  │   ├─ home/ anniversary/ pet/      #   首页 / 纪念日 / 宠物
+│  │   ├─ gacha/ album/ shop/ orders/  #   抽卡 / 心动档案 / 商城 / 订单
+│  │   ├─ game/ profile/ common/       #   小游戏 / 个人资料 / 通用
+│  ├─ admin/                           # 内置管理/配置页
+│  ├─ hooks/                           # 自定义 Hooks
+│  ├─ services/                        # 数据与业务服务
+│  ├─ lib/                             # 工具与布局数据(部分由插件自动生成,见下)
+│  └─ assets/desktop-assets/           # 立绘、视频等媒体素材(经 Git LFS 管理)
+├─ android/                            # Capacitor 生成的 Android 原生工程
+├─ public/                             # 原样拷贝的静态资源
+├─ dist/                               # 构建产物(被 .gitignore 忽略,由 npm run build 生成)
+├─ capacitor.config.ts                # Capacitor 配置(appId / appName / webDir)
+└─ vite.config.ts                     # Vite 配置 + 自定义布局编写插件
+```
+
+## 可用脚本
+
+| 命令 | 作用 |
+| --- | --- |
+| `npm run dev` | 启动 Vite 开发服务器(`0.0.0.0:5176`,支持真机/局域网调试) |
+| `npm run build` | 类型检查(`tsc -b`)+ Vite 构建,输出到 `dist/` |
+| `npm run cap:sync` | `npx cap sync android`,把 `dist/` 同步进 Android 工程 |
+| `npm run android:sync` | 一步到位:先 `build` 再 `cap:sync` |
+| `npm run check:android` | 自检本机 Android 构建环境 |
+| `npm run lint` | 运行 ESLint |
+| `npm run preview` | 本地预览 `dist/` 构建产物 |
+
+## 开发说明
+
+### 首页布局可视化编辑
+
+`vite.config.ts` 内置了一个 `layoutWriterPlugin`:在**开发模式**下,前端可把首页各元素(头像、纪念日素材、底部图标等)的位置通过 `POST /__vtubermini/save-layouts` 回写到 `src/lib/home-layout.ts` 与 `src/lib/anniversary-image-layout.ts`。这些布局文件因此是**半自动生成**的——通过可视化调整保存,而非手改坐标。该接口仅在 dev server 生效,生产构建不包含。
+
+### App 信息
+
+- `appId`:`com.vtubermini.app`
+- `appName`:`VTuber Mini`
+- 该模板按「一次服务一位主播」设计,可作为同类粉丝陪伴 App 的可复用底座。