From da09739ae1fab121bce9dcef311f6776984fb520 Mon Sep 17 00:00:00 2001
From: danaisuiyuan <mac@danaisuuandeMBP.lan>
Date: Thu, 21 May 2026 06:50:53 +0800
Subject: [PATCH] docs: update syj deployment guide

---
 docs/project-shaoyaoju/deploy-syj.md | 314 +++++++++++++++++++++++++++
 1 file changed, 314 insertions(+)
 create mode 100644 docs/project-shaoyaoju/deploy-syj.md

diff --git a/docs/project-shaoyaoju/deploy-syj.md b/docs/project-shaoyaoju/deploy-syj.md
new file mode 100644
index 00000000..2a1bfc6d
--- /dev/null
+++ b/docs/project-shaoyaoju/deploy-syj.md
@@ -0,0 +1,314 @@
+# syj 商城变体部署手册
+
+少药局线上站点：`https://syj.fsgx.cn`
+
+一键发布脚本：`pro_v3.5.1/deploy/release-syj.sh`
+
+发布方式：本地当前分支构建 admin → 同步 `public/admin/` 和后端代码 → 远端切换 `.env-syj` → `php think clear` → Swoole reload → 健康检查 → 失败自动回滚。
+
+覆盖范围：
+- 后端 PHP 代码
+- admin 前端构建产物 `public/admin/`
+- 远端 `.env` 使用 `.env-syj`
+- Swoole 平滑 reload
+- 远端备份与回滚
+
+不覆盖：
+- `view/uniapp_v2/` 小程序端，需要 HBuilderX / 微信开发者工具单独发布
+- `view/uniapp/`
+- Composer 依赖安装
+- 数据库结构迁移和配置项插入
+
+---
+
+## 1. 本次上线
+
+本次已推送分支：`syj-bypass-auth`
+
+本次提交：
+
+```bash
+673a19b3 feat: add channel code integral reward
+```
+
+主要内容：
+- `admin/agent/agent_manage/index` 增加“小程序推广码”列，并将“推广用户数量”移动到“小程序推广码”后面。
+- 积分配置新表单增加：
+  - 渠道码积分奖励
+  - 渠道分销员UID
+  - 渠道码奖励积分
+- 新用户扫描指定分销员小程序分享二维码注册后，可按配置发放积分，仅新用户注册事件触发，且通过积分账单防重复。
+- 修复 `/admin/system/maintain/clear/index` 清除缓存、清除日志在目录不存在时可能报错的问题。
+
+上线命令：
+
+```bash
+cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
+git fetch origin
+git checkout syj-bypass-auth
+git pull --ff-only origin syj-bypass-auth
+bash deploy/release-syj.sh
+```
+
+如果确认 admin 已经构建过，可跳过构建：
+
+```bash
+bash deploy/release-syj.sh --skip-build
+```
+
+---
+
+## 2. 发布前检查
+
+```bash
+cd /Users/mac/scott2026/huangjingfen
+git branch --show-current
+git log -1 --oneline
+git status --short
+```
+
+正常应在：
+
+```bash
+syj-bypass-auth
+```
+
+确认远端可访问：
+
+```bash
+ssh root@8.140.50.89 'cd /www/wwwroot/syj.fsgx.cn && pwd && php -v | head -1'
+curl -ksS -o /dev/null -w "api/version -> %{http_code}\n" https://syj.fsgx.cn/api/version
+curl -ksS -o /dev/null -w "admin -> %{http_code}\n" https://syj.fsgx.cn/admin/
+```
+
+确认本次代码在本地：
+
+```bash
+rg -n "channel_code_integral_status|channel_code_agent_uid|channel_code_give_integral" \
+  pro_v3.5.1/app/services/system/config/SystemConfigServices.php \
+  pro_v3.5.1/app/listener/user/Register.php
+
+rg -n "小程序推广码|推广用户数量|showXcxCode" \
+  pro_v3.5.1/view/admin/src/pages/agent/agentManage.vue
+```
+
+---
+
+## 3. 数据库配置项
+
+发布脚本不会自动写数据库。上线前确认 `eb_system_config` 已存在以下配置项，并归属积分配置分组 `config_tab_id = 11`。
+
+查询：
+
+```bash
+mysql -h8.140.50.89 -P3306 -usyj-shop -p syj-shop -e "
+SELECT menu_name, config_tab_id, type, input_type, info, value, \`desc\`, parameter, sort, status
+FROM eb_system_config
+WHERE menu_name IN (
+  'channel_code_integral_status',
+  'channel_code_agent_uid',
+  'channel_code_give_integral'
+);"
+```
+
+缺失时插入：
+
+```sql
+INSERT INTO eb_system_config
+  (config_tab_id, menu_name, type, input_type, config_tab, parameter, upload_type, required, width, high, value, info, `desc`, sort, status)
+SELECT 11, 'channel_code_integral_status', 'radio', '', '', '1=>开启\n0=>关闭', 0, '', 0, 0, '0',
+       '渠道码积分奖励',
+       '开启后，新用户扫描指定分销员的小程序分享二维码注册可获得积分奖励，仅限新用户领取一次',
+       7, 1
+WHERE NOT EXISTS (SELECT 1 FROM eb_system_config WHERE menu_name = 'channel_code_integral_status');
+
+INSERT INTO eb_system_config
+  (config_tab_id, menu_name, type, input_type, config_tab, parameter, upload_type, required, width, high, value, info, `desc`, sort, status)
+SELECT 11, 'channel_code_agent_uid', 'text', 'number', '', '', 0, '', 0, 0, '0',
+       '渠道分销员UID',
+       '填写分销员UID；该分销员的小程序推广二维码将作为渠道码',
+       6, 1
+WHERE NOT EXISTS (SELECT 1 FROM eb_system_config WHERE menu_name = 'channel_code_agent_uid');
+
+INSERT INTO eb_system_config
+  (config_tab_id, menu_name, type, input_type, config_tab, parameter, upload_type, required, width, high, value, info, `desc`, sort, status)
+SELECT 11, 'channel_code_give_integral', 'text', 'number', '', '', 0, '', 0, 0, '0',
+       '渠道码奖励积分',
+       '新用户扫描渠道码注册后获得的积分数量；设置为0则不发放',
+       5, 1
+WHERE NOT EXISTS (SELECT 1 FROM eb_system_config WHERE menu_name = 'channel_code_give_integral');
+```
+
+后台配置路径：
+
+```text
+admin/marketing/integral/system_config/3/11
+```
+
+配置说明：
+- `渠道码积分奖励`：开启后生效。
+- `渠道分销员UID`：填写作为渠道码来源的分销员 UID。
+- `渠道码奖励积分`：新用户扫描该分销员小程序推广码注册后获得的积分数。
+
+---
+
+## 4. 日常发布
+
+```bash
+cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
+bash deploy/release-syj.sh
+```
+
+脚本阶段：
+1. `Pre-flight checks`：校验分支、`.env-syj`、远端目录、admin 生产 API 地址。
+2. `Build admin`：在 `view/admin` 执行 `npm run build`。
+3. `Sync admin dist -> public/admin/`：把 `view/admin/dist/` 同步到 `public/admin/`。
+4. `Release tag`：生成 `YYYYMMDD-HHMMSS-<git sha>`。
+5. `rsync`：同步项目到 `/www/wwwroot/syj.fsgx.cn`，旧文件备份到 `/www/wwwroot/syj.fsgx.cn-bak/<tag>/`。
+6. `Remote`：远端 `.env-syj` 覆盖 `.env`，执行 `php think clear`，reload Swoole。
+7. `Healthcheck`：检查 `https://syj.fsgx.cn/api/version` 和 `https://syj.fsgx.cn/admin/`。
+8. 成功后写入本地 `pro_v3.5.1/deploy/.last-release`。
+
+可选参数：
+- `--dry-run`：只预览 rsync 改动，不改远端。
+- `--skip-build`：复用已有 `view/admin/dist/`。
+- `--rollback <tag>`：回滚指定备份。
+
+---
+
+## 5. 上线后验收
+
+基础健康：
+
+```bash
+curl -ksS -o /dev/null -w "api/version -> %{http_code}\n" https://syj.fsgx.cn/api/version
+curl -ksS -o /dev/null -w "admin -> %{http_code}\n" https://syj.fsgx.cn/admin/
+```
+
+远端代码确认：
+
+```bash
+ssh root@8.140.50.89 'cd /www/wwwroot/syj.fsgx.cn && \
+grep -n "channel_code_integral_status" app/services/system/config/SystemConfigServices.php && \
+grep -n "giveChannelCodeIntegral" app/listener/user/Register.php && \
+grep -n "小程序推广码" view/admin/src/pages/agent/agentManage.vue public/admin/js/*.js 2>/dev/null | head'
+```
+
+后台页面验收：
+- `admin/marketing/integral/system_config/3/11` 能看到 3 个渠道码积分配置项。
+- `admin/agent/agent_manage/index` 列顺序为：`小程序推广码` → `推广用户数量` → `上级推广人`。
+- 点击“小程序推广码”的“查看”能打开二维码弹窗。
+- `/admin/system/maintain/clear/index` 清除缓存、清除日志不再报错。
+
+业务验收：
+1. 在积分配置页开启“渠道码积分奖励”。
+2. 设置“渠道分销员UID”和“渠道码奖励积分”。
+3. 使用该分销员的小程序推广码新注册用户。
+4. 新用户积分增加对应数量。
+5. `eb_user_bill` 中出现 `type = channel_code_add` 的积分账单。
+6. 同一用户不会重复领取。
+
+查询账单：
+
+```sql
+SELECT uid, category, type, title, number, balance, mark, add_time
+FROM eb_user_bill
+WHERE type = 'channel_code_add'
+ORDER BY id DESC
+LIMIT 20;
+```
+
+---
+
+## 6. 回滚
+
+查看最近备份：
+
+```bash
+ssh root@8.140.50.89 'ls -1t /www/wwwroot/syj.fsgx.cn-bak | head -10'
+```
+
+执行回滚：
+
+```bash
+cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
+bash deploy/release-syj.sh --rollback 20260521-005301-673a19b3
+```
+
+说明：
+- `.env` 不在回滚范围内，避免误覆盖运行环境。
+- 数据库配置项和业务数据不随脚本回滚。
+- 若本次上线已经产生积分账单，代码回滚不会自动撤销账单，需要业务人工处理。
+
+---
+
+## 7. 故障排查
+
+| 现象 | 排查 |
+|------|------|
+| 后台看不到新增配置项 | 确认远端代码已更新、Swoole 已 reload、`eb_system_config` 三条配置存在且 `config_tab_id = 11` |
+| admin 页面还是旧列顺序 | 确认 `public/admin/` 是最新构建产物，浏览器强刷或清缓存 |
+| 新用户未获得积分 | 检查配置是否开启、分销员 UID 是否正确、扫码二维码是否 `third_type = spread_routine` |
+| 重复发积分 | 查询 `eb_user_bill.type = channel_code_add`，代码按用户已有该账单防重复 |
+| 清缓存/清日志失败 | 看 `runtime/log/` 和 `app/services/system/log/ClearServices.php` 是否已更新 |
+| `/api/version` 不是 200 | 看 Swoole 是否运行、Nginx 反代、ThinkPHP 日志 |
+| reload 后代码未生效 | 宝塔 Supervisor 兜底：`/www/server/panel/pyenv/bin/supervisorctl restart pro3.5.1:pro3.5.1_00` |
+| rsync 提示 `.user.ini` | `deploy/rsync-exclude.txt` 已排除 `public/.user.ini`，不需要删除远端文件 |
+
+远端常用命令：
+
+```bash
+ssh root@8.140.50.89 'cd /www/wwwroot/syj.fsgx.cn && php think clear'
+ssh root@8.140.50.89 'ps aux | grep "php think swoole" | grep -v grep'
+ssh root@8.140.50.89 'tail -100 /www/wwwroot/syj.fsgx.cn/runtime/swoole/swoole.log'
+ssh root@8.140.50.89 'tail -100 /www/server/panel/plugin/supervisor/log/pro3.5.1.out.log'
+```
+
+---
+
+## 8. 本机环境
+
+启动本机后端和 admin：
+
+```bash
+cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
+bash deploy/start-local-syj.sh start
+```
+
+常用命令：
+
+```bash
+bash deploy/start-local-syj.sh status
+bash deploy/start-local-syj.sh restart
+bash deploy/start-local-syj.sh logs
+bash deploy/start-local-syj.sh stop
+```
+
+本机地址：
+- 后端：`http://127.0.0.1:20199`
+- admin：`http://localhost:8085/admin/`
+
+注意：
+- `view/admin/.env.dev` 需要指向 `http://127.0.0.1:20199/adminapi` 才会请求本机后端。
+- `view/uniapp_v2/` 不由本脚本启动。
+
+---
+
+## 9. 服务器留档
+
+路径：
+- 项目：`/www/wwwroot/syj.fsgx.cn/`
+- 备份：`/www/wwwroot/syj.fsgx.cn-bak/`
+- Swoole 日志：`/www/wwwroot/syj.fsgx.cn/runtime/swoole/swoole.log`
+- Supervisor 日志：`/www/server/panel/plugin/supervisor/log/pro3.5.1.out.log`
+- ThinkPHP 日志：`/www/wwwroot/syj.fsgx.cn/runtime/log/`
+
+Nginx 要点：
+- `/admin/` 指向 `public/admin/`
+- `/api/`、`/adminapi/` 由 Swoole 处理
+- Swoole 监听端口：`20199`
+
+`.env-syj`：
+- `[DATABASE]` 指向 `8.140.50.89`
+- `[REDIS]` 指向 `8.140.50.89`
+- 生产建议 `APP_DEBUG = false`，当前脚本不会强制改该值