From d400512ea2af5b4bbd400984484ed55060e5e42e Mon Sep 17 00:00:00 2001
From: msh-agent <agent@msh.local>
Date: Thu, 21 May 2026 09:44:28 +0800
Subject: [PATCH] docs: add source handover guide

---
 docs/项目移交说明.md | 176 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 docs/项目移交说明.md

diff --git a/docs/项目移交说明.md b/docs/项目移交说明.md
new file mode 100644
index 0000000..53585dd
--- /dev/null
+++ b/docs/项目移交说明.md
@@ -0,0 +1,176 @@
+# 项目源代码移交说明
+
+## 1. 移交基线
+
+- 项目名称：MSH System（慢生活智能营养专家）
+- 当前移交分支：`fix/test-feedback-0403`
+- 推荐移交 tag：`handover-2026-05-21`
+- 仓库地址：`http://49.235.131.69:3000/scottpan/msh-system.git`
+- 移交日期：2026-05-21
+
+接收方应优先基于指定 tag 或分支拉取代码，避免使用本地未提交工作区作为交付源。
+
+## 2. 源码范围
+
+本次源码移交包含：
+
+- `msh_crmeb_22/`：Java 主后端，多模块 Maven 工程。
+- `msh_single_admin/`：管理后台前端。
+- `msh_single_uniapp/`：UniApp 移动端、H5、小程序前端。
+- `docs/`：产品、架构、测试、数据库、SQL 迁移等文档。
+- `scripts/`：辅助脚本。
+- `README.md`：项目总览与快速入口。
+
+以下内容不作为源码交付主体：
+
+- `node_modules/`
+- `target/`
+- `dist/`
+- `upload/` 中真实用户上传文件
+- `front_log/`、`msh_crmeb_22/front_log/`、`msh_crmeb_22/crmeb_*_log/`
+- `tests/e2e/test-results/`、`playwright-report/`
+- `.DS_Store`、本地调试日志、`.env` 私有环境文件
+
+## 3. 技术栈概览
+
+- 后端：JDK 1.8、Spring Boot、Maven、MyBatis-Plus、MySQL、Redis。
+- 管理端：Vue 2、Element UI、Node.js/npm。
+- 移动端：UniApp、Vue 2、HBuilderX、微信/支付宝等多端配置。
+- 第三方能力：对象存储、微信/支付宝支付、Coze、KieAI、腾讯云 ASR 等。
+
+## 4. 拉取代码
+
+```bash
+git clone http://49.235.131.69:3000/scottpan/msh-system.git
+cd msh-system
+git checkout fix/test-feedback-0403
+```
+
+若已创建移交 tag，建议使用：
+
+```bash
+git checkout handover-2026-05-21
+```
+
+## 5. 后端启动与构建
+
+```bash
+cd msh_crmeb_22
+mvn clean package
+```
+
+C 端 API：
+
+```bash
+./shell/startFront.sh
+```
+
+管理端 API：
+
+```bash
+./shell/startAdmin.sh
+```
+
+常用配置文件位置：
+
+- `msh_crmeb_22/crmeb-front/src/main/resources/application.yml`
+- `msh_crmeb_22/crmeb-front/src/main/resources/application-*.yml`
+- `msh_crmeb_22/crmeb-admin/src/main/resources/application.yml`
+- `msh_crmeb_22/crmeb-admin/src/main/resources/application-*.yml`
+
+接收方需按实际环境配置 MySQL、Redis、域名、文件存储、支付、AI Key 等。
+
+## 6. 管理后台启动与构建
+
+```bash
+cd msh_single_admin
+npm install
+npm run dev
+```
+
+生产构建：
+
+```bash
+npm run build:prod
+```
+
+常用配置文件：
+
+- `msh_single_admin/.env.development`
+- `msh_single_admin/.env.production`
+- `msh_single_admin/.env.staging`
+- `msh_single_admin/vue.config.js`
+
+## 7. UniApp 启动与构建
+
+```bash
+cd msh_single_uniapp
+npm install
+npm run serve
+```
+
+推荐使用 HBuilderX 打开 `msh_single_uniapp/`，按目标平台运行到 H5、微信小程序或 App。
+
+常用配置文件：
+
+- `msh_single_uniapp/config/app.js`：API 域名与请求配置。
+- `msh_single_uniapp/manifest.json`：应用名、版本、AppId、平台能力配置。
+- `msh_single_uniapp/pages.json`：页面路由与导航栏配置。
+
+## 8. 数据库与 SQL
+
+主要 SQL 文件：
+
+- `docs/db/shop-msh.sql`：数据库基线或导出文件。
+- `docs/sql/`：业务迁移与初始化脚本。
+- `msh_crmeb_22/sql/v2_dish_image_cache.sql`：菜品图片缓存表。
+- `sql/add_ai_chat_model_config.sql`：AI 聊天模型配置脚本。
+
+建议接收方使用测试环境先完成数据库恢复，再按 SQL 文件时间与业务说明执行迁移。
+
+## 9. 敏感信息交接
+
+以下信息不得直接写入源码仓库，应通过安全渠道单独交接：
+
+- 服务器 SSH、面板、数据库、Redis 账号密码。
+- OSS/COS/七牛等对象存储 Key。
+- 微信小程序、公众号、微信支付、支付宝配置与证书。
+- Coze、KieAI、腾讯云 ASR 等 API Key。
+- 域名、SSL 证书、短信、地图等第三方平台账号。
+
+建议源码中保留示例值或环境变量占位，由接收方在部署环境注入真实值。
+
+## 10. 部署建议
+
+后端：
+
+1. 在服务器安装 JDK 1.8、Maven、MySQL、Redis。
+2. 执行 `mvn clean package` 生成 JAR。
+3. 将 JAR 与对应 `application-*.yml` 放到部署目录。
+4. 使用 `shell/startFront.sh`、`shell/startAdmin.sh` 启动。
+5. 用 Nginx 反向代理到 C 端和管理端 API 端口。
+
+前端：
+
+1. 管理后台执行生产构建，部署 `dist/` 到静态服务器。
+2. UniApp H5 构建产物部署到静态服务器。
+3. 小程序/App 使用 HBuilderX 或平台工具完成打包上传。
+
+## 11. 验收清单
+
+接收方完成以下动作后，可视为源码移交成功：
+
+- 能拉取指定分支或 tag。
+- 能根据文档启动后端 C 端 API 与管理端 API。
+- 能启动管理后台并访问登录页。
+- 能运行 UniApp H5 或小程序开发环境。
+- 能恢复测试数据库并完成核心接口访问。
+- 能独立完成一次后端打包与前端构建。
+- 已收到生产配置、账号、证书、第三方平台权限等非源码资料。
+
+## 12. 已知注意事项
+
+- 仓库中存在历史模块名与配置前缀，例如 `crmeb-front`、`crmeb-admin`、`crmeb.ignored`、`crmebimage`，这些属于运行契约或资源路径，未经迁移不要直接改名。
+- `upload/` 与日志目录通常包含运行时数据，不建议随源码交付。
+- 真实生产密钥如已出现在历史配置中，接收方应在接手后尽快轮换。
+- 移交前应确认工作区无未提交的交付改动：`git status --short`。