From 130f5321168b864f6b5d9025b557fc1e7c799755 Mon Sep 17 00:00:00 2001
From: huazhongmin <peanut_hzm@163.com>
Date: Sat, 7 Mar 2026 18:06:57 +0800
Subject: [PATCH] =?UTF-8?q?docs(mini-program):=20=E6=9B=B4=E6=96=B0=20READ?=
 =?UTF-8?q?ME=20=E6=B7=BB=E5=8A=A0=E7=BC=96=E8=AF=91=E5=92=8C=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加快速开始指南（安装依赖、开发模式）
- 添加微信小程序编译和预览步骤
- 添加 H5 编译和部署说明
- 添加环境配置说明
- 添加项目结构说明
- 添加常见问题和部署上线流程

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 mini-program/README.md | 226 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 223 insertions(+), 3 deletions(-)

diff --git a/mini-program/README.md b/mini-program/README.md
index 33895ab..674be37 100644
--- a/mini-program/README.md
+++ b/mini-program/README.md
@@ -1,5 +1,225 @@
-# Vue 3 + TypeScript + Vite
+# 人生 OS 微信小程序
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+基于 UniApp + Vue 3 的人生 OS 微信小程序，与 Web 端（life-script）共享后端 API。
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+## 技术栈
+
+- **框架**: UniApp
+- **语言**: Vue 3 + TypeScript
+- **状态管理**: Pinia
+- **HTTP 请求**: uni.request 封装
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+cd mini-program
+npm install
+# 或使用 pnpm
+pnpm install
+```
+
+### 2. 开发模式
+
+#### 微信小程序开发预览
+
+```bash
+# 启动微信小程序开发服务器
+npm run dev:mp-weixin
+# 或
+pnpm dev:mp-weixin
+```
+
+启动后，打开**微信开发者工具**：
+1. 导入项目目录：`mini-program/unpackage/dist/dev/mp-weixin`
+2. 在开发者工具中可以实时预览和调试
+
+#### H5 开发预览
+
+```bash
+# 启动 H5 开发服务器
+npm run dev:h5
+# 或
+pnpm dev:h5
+```
+
+启动后，在浏览器访问：`http://localhost:5173`
+
+### 3. 编译打包
+
+#### 编译为微信小程序
+
+```bash
+# 生产环境编译
+npm run build:mp-weixin
+# 或
+pnpm build:mp-weixin
+```
+
+编译输出目录：`unpackage/dist/build/mp-weixin`
+
+**部署步骤**：
+1. 打开微信开发者工具
+2. 导入目录：`mini-program/unpackage/dist/build/mp-weixin`
+3. 点击「上传」按钮，上传代码到微信公众平台
+4. 登录微信公众平台进行版本提交和发布
+
+#### 编译为 H5
+
+```bash
+# 生产环境编译
+npm run build:h5
+# 或
+pnpm build:h5
+```
+
+编译输出目录：`unpackage/dist/build/h5`
+
+### 4. 环境配置
+
+项目使用 `.env` 文件管理环境变量：
+
+| 文件 | 说明 |
+|------|------|
+| `.env.development` | 开发环境配置 |
+| `.env.production` | 生产环境配置 |
+
+**开发环境配置**（`.env.development`）：
+```bash
+VITE_APP_ENV=dev
+VITE_API_BASE_URL=http://localhost:19089
+VITE_WS_URL=ws://localhost:19089
+VITE_DEBUG=true
+```
+
+**生产环境配置**（`.env.production`）：
+```bash
+VITE_APP_ENV=prod
+VITE_API_BASE_URL=http://101.200.208.45:19089/api
+VITE_WS_URL=ws://101.200.208.45:19089
+VITE_DEBUG=false
+```
+
+## 项目结构
+
+```
+mini-program/
+├── src/
+│   ├── pages/              # 页面目录
+│   │   ├── splash/         # 启动页
+│   │   ├── login/          # 登录页
+│   │   ├── onboarding/     # 引导页
+│   │   ├── main/           # 主页容器
+│   │   │   ├── index.vue   # 主页面
+│   │   │   ├── RecordView.vue  # 记录页
+│   │   │   ├── ScriptView.vue  # 剧本页
+│   │   │   └── PathView.vue    # 路径页
+│   │   └── profile/        # 个人页
+│   ├── components/         # 公共组件
+│   │   └── MusicPlayer.vue # 音乐播放器
+│   ├── services/           # API 服务层
+│   │   ├── request.js      # 请求封装
+│   │   ├── auth.js         # 认证服务
+│   │   ├── userProfile.js  # 用户档案服务
+│   │   ├── lifeEvent.js    # 生命事件服务
+│   │   ├── epicScript.js   # 剧本服务
+│   │   └── lifePath.js     # 路径服务
+│   ├── stores/             # 状态管理
+│   │   └── app.js          # 应用状态
+│   ├── config/             # 配置文件
+│   │   └── env.js          # 环境配置
+│   ├── static/             # 静态资源
+│   ├── App.vue             # 应用入口
+│   ├── main.js             # 应用入口 JS
+│   ├── manifest.json       # 应用配置
+│   ├── pages.json          # 页面配置
+│   └── uni.scss            # 全局样式
+├── .env.development        # 开发环境变量
+├── .env.production         # 生产环境变量
+├── package.json            # 项目依赖
+├── tsconfig.json           # TypeScript 配置
+└── vite.config.js          # Vite 配置
+```
+
+## 开发说明
+
+### API 接口
+
+小程序与 Web 端（life-script）共享同一套后端 API，接口文档参考 life-script 项目。
+
+主要服务包括：
+- **auth.js**: 用户认证（登录、注册、验证码）
+- **userProfile.js**: 用户档案管理
+- **lifeEvent.js**: 生命事件记录
+- **epicScript.js**: AI 剧本生成
+- **lifePath.js**: 实现路径规划
+
+### 样式规范
+
+小程序使用全局样式 + 组件作用域样式：
+
+- **全局样式**: `src/App.vue` 中定义，包括玻璃态效果、渐变按钮、动画等
+- **主题色**:
+  - 主背景：`#0F071A`
+  - 渐变顶部：`#1A0B2E`
+  - 渐变底部：`#050208`
+  - 主紫色：`#A855F7`
+  - 浅紫色：`#C084FC`
+  - 粉色：`#E879F9`
+
+### 状态管理
+
+使用 Pinia 进行状态管理，主要状态包括：
+- `isLoggedIn`: 登录状态
+- `userProfile`: 用户档案
+- `events`: 生命事件列表
+- `scripts`: 剧本列表
+- `currentPath`: 当前实现路径
+
+## 常见问题
+
+### 端口占用
+
+启动开发服务器前，如遇端口被占用：
+
+```bash
+# 清理占用端口的 vite 进程
+./scripts/cleanup-all-vite.sh
+# 或直接运行
+vite
+```
+
+### 跨域问题
+
+开发环境如遇跨域问题，请确保：
+1. 后端 CORS 配置包含当前开发端口（5173-5190）
+2. 使用正确的 API_BASE_URL
+
+### 真机预览
+
+1. 在微信开发者工具中点击「预览」
+2. 使用微信扫描二维码
+3. 在真机上查看效果
+
+## 部署上线
+
+### 小程序发布流程
+
+1. **代码编译**: `npm run build:mp-weixin`
+2. **导入工具**: 微信开发者工具导入编译后的目录
+3. **上传代码**: 点击「上传」按钮
+4. **版本管理**: 登录微信公众平台进行版本提交
+5. **审核发布**: 提交审核后等待微信官方审核
+
+### H5 部署
+
+1. **代码编译**: `npm run build:h5`
+2. **上传服务器**: 将 `unpackage/dist/build/h5` 目录部署到服务器
+3. **配置反向代理**: 配置 Nginx 反向代理后端 API
+
+## 参考资料
+
+- [UniApp 官方文档](https://uniapp.dcloud.net.cn/)
+- [Vue 3 官方文档](https://vuejs.org/)
+- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)