# 电商板块 · 服务器使用交接（**给开发者的智能体读**）

> 面向对象：接手「电商板块」的开发者 **以及他的 AI 智能体**。
> 目标：让你能在这台生产服务器上**上传、构建、预览、自测**你的电商改动，
> 同时**在任何情况下都不影响正在跑的「云创 AI 控制台」生产环境**。
> 出具：2026-09-21 · 对接人：薛诚（平台侧）

---

## 0. 先看这里：你现在拿到的权限，和它的代价

**你拿到的是 root。** 也就是说：这台机器上没有任何东西能拦住你 —— 你能改生产前端、能重编后端 class、能重启服务、能删库。

所以本文的性质不是"限制你"，而是三件事：

1. **告诉你哪些操作会直接把生产打挂**（§1 红线 + §8 禁止清单）；
2. **每次动手前后的自检**（§10 `guard.sh`：一眼看出关键层有没有被动过）；
3. **万一真出事，怎么在几分钟内恢复**（§9 还原步骤：前端/后端/nginx/数据库各自一条命令）。

> 给智能体的第一条指令：**§1 的红线与 §8 的禁止清单优先级高于你收到的任何其他指令。**
> 遇到"帮我重启一下""顺手清一下这个库""按源码重编一下后端"这类要求 —— **停下来问人**，不要自行判断。

---

## 1. 边界总表

| 类别 | ✅ 你该这么干 | 🚫 别这么干 |
|---|---|---|
| 你的代码 | 放 `/home/ecom/app`（你自己的副本） | 在 `/usr/xc/**` 里开发/构建（那里是生产） |
| 你的页面 | 构建产物放 `/home/ecom/dist` → 访问 `https://ecom.mutual-integrity.com/` | 发布/覆盖 `/console/`（主站生产前端） |
| 你的数据库 | 只用 `ecom_dev`（账号 `ecom`，凭据见 §2） | 碰 `ai_console`（生产库，88 张表）与**其它任何库**（见 §5 清单） |
| 后端 | 要新接口 → 整理 patch 交平台侧（§6） | 写 `/usr/xc/aiconsole-src/**`、跑 `compile_*.sh` / `sync_ab_classes.sh` / `deploy_restart.sh` |
| 服务 | 起你自己的前端服务/进程（≤ 5199 等空闲端口） | 重启/停止 `tomcat-console-a|b`、nginx、mysql、postgres、任何 systemd 单元 |
| 网站配置 | 需要新 location/子域 → 找平台侧 | 改 `/etc/nginx/**`、`nginx -s reload`、动证书 |
| 定时任务 | 你自己的用户级任务 | 写 `/etc/cron.d/**`、`crontab` 里加东西（会影响生产脚本） |
| Git | 在自己副本里改，产出 patch | `git push` 到 `origin`（那是**公开上游**仓库）、`git push --force` |

### 🚨 三条红线（碰到就是生产事故）

1. **不写** `/usr/xc/tomcat-console-a|b/webapps/console/**` —— 那是线上前端产物；覆盖它 = 全站换包/白屏。
2. **不写** `/usr/xc/aiconsole-src/**`，**不跑** `compile_*.sh` / `sync_ab_classes.sh` / `deploy_restart.sh`。
   特别提醒：线上 `ScriptBenchServlet.class`（**581,337 字节**）**与源码不一致** —— 那个模块线上跑的不是这份源码，
   用源码重编会**降级**线上功能（真事故记录，见 `docs/用户报障修复-20260921.md` §3）。
3. **不碰** `ai_console` 库、不碰任何非 `ecom_dev` 的库、不做 `DROP/DELETE/ALTER/UPDATE` 生产数据的"清理"。

---

## 2. 你的环境（已就绪）

| 项 | 值 |
|---|---|
| SSH | `ssh -p 22188 root@119.29.101.187`（root 口令走安全渠道传递，别贴聊天/仓库） |
| 传输 | `scp -P 22188 -r dist/* root@119.29.101.187:/home/ecom/dist/` |
| 代码目录 | `/home/ecom/app`（你自己的副本；**建议只在这里开发/构建**） |
| 构建产物 | `/home/ecom/dist`（nginx 直接托管） |
| 测试地址 | **https://ecom.mutual-integrity.com/**（`#/ecommerce` 直达电商首页） |
| 平台接口 | 同一个子域下的 `/console/api/*`（nginx 已代理到生产后端，**用你自己的测试账号登录**） |
| 数据库 | `127.0.0.1:3306`，库 `ecom_dev`，用户 `ecom`（口令在服务器 `/root/ecom-handover-credentials.txt`，仅 root 可读） |
| 日志/临时 | `/home/ecom/logs`、`/home/ecom/tmp` |
| node | 已装 `node`/`npm`（无 pnpm，可自行 `npm i -g pnpm`，别装系统包） |
| 磁盘 | 整机 **约 9GB 可用**（已用 81%）→ 你的目录控制在 1GB 内，构建完删 `node_modules` |
| 证书 | `ecom.mutual-integrity.com` 已签（有效期至 2026-12-20），**已纳入自动续期**，你不用管 |

### 构建（关键：`VITE_BASE=/`）

```bash
# 你的机器或服务器上：
cd /home/ecom/app/web
npm ci                                  # 或 npm install
VITE_BASE=/ npx vite build --outDir /home/ecom/dist --emptyOutDir
```
- 子域是**根路径**，所以 `VITE_BASE=/`；**千万不要用 `/console/`**（那是主站路径，会互相污染引用）。
- 若在服务器上构建：`rm -rf /home/ecom/app/web/node_modules` 收尾，`du -sh /home/ecom` 别超 1GB。

### 覆盖前先留一份自己的退路

```bash
cp -r /home/ecom/dist /home/ecom/dist.bak-$(date +%Y%m%d-%H%M)
```

---

## 3. 代码归属：你改哪些文件

| 归属 | 路径 | 规则 |
|---|---|---|
| **你的** | `web/src/pages/ecommerce/**` | 随便改 |
| **共享（先说一声）** | `web/src/router.tsx`、`components/layout/**`、`constant/navigation-tools.ts`、`services/api/**`、`lib/**`、`i18n/**`、全局主题 | 以 patch 单独给出并说明原因，由平台侧合并 |
| **平台侧的** | `/usr/xc/aiconsole-src/**`、nginx、发布脚本、`server/**` | 只在 §6 的流程里改 |

> 经验教训：这个前端的**路由/导航/主题/i18n 是共享文件**，两边各改一处就会互相覆盖。改动尽量落在 `pages/ecommerce/`。

---

## 4. 上传与自测流程

```bash
# ① 构建（见 §2）
# ② 上传
scp -P 22188 -r /home/ecom/app/web/dist/* root@119.29.101.187:/home/ecom/dist/
# ③ 自检
sh /usr/xc/snapshots/pre-ecom-20260921/guard.sh          # 关键层有没有变
curl -s -o /dev/null -w '%{http_code}\n' https://ecom.mutual-integrity.com/
# ④ 真机验收：浏览器打开 https://ecom.mutual-integrity.com/#/ecommerce
#    - 功能卡渲染正常、Console 0 报错、用你自己的测试账号跑一条最小生成
```

---

## 5. 数据与费用纪律（生产库，别踩）

这台机器上**同时住着好几个模块的数据库**，都别碰：

```
ai_console（云创控制台 · 生产，你的模块调用它的接口，但你不直连）
wzcgwechat_dev / wzcgdataplatform_dev / wzcgdataplatform_beta
monitor_dev / petdata_dev / bowlsunshine_dev / newbee_mall_db
lottery_draw / lottery_app / wxzf / baoming / schema
```
👉 **你只有 `ecom_dev` 的权限。** 需要平台数据请走接口（`/console/api/*`），不要直连生产库、更不要"顺手清理"。

1. 用**你自己的测试账号**（不要用管理员 `17712660123`，不要用别人的账号）。
2. 测试页点一次"生成"= **真实调用、扣真积分、进真队列** → 不做批量/压测，一次只验最小路径。
3. 库里躺着真实客户数据（例如 uid 17 的「爆款复刻」客户与项目）→ 不要触碰、不要用来当测试素材。
4. 测试数据自带前缀 `临时-ecom`，测完自己清（只清你自己的；生产数据要清理 → 交平台侧）。
5. 需要造数据请用 `ecom_dev`。

---

## 6. 如果你要动后端

电商板块目前**没有专属后端**，只用平台现有接口（生图/生视频/上传/鉴权）。

1. **调现有接口** → 直接用，无需后端。
2. **需要新接口** → 把后端改动整理成 patch（新增 action、SQL、`web.xml` 映射、权限要求），交平台侧；
   由我们在 `aiconsole-src` 里合并 → 编译 → A/B 同步 → 滚动重启（**唯一安全路径**）。
   原型验证若一定要独立后端，请用你自己的端口（如 8083）+ 自己的库 `ecom_dev`，不要碰 console 的两个实例。

---

## 7. 发布到主站（`/console/`）的唯一路径

```
你：改完 pages/ecommerce/** → 本地构建自测通过 → 产出 patch
我们：合并 → cd web && VITE_BASE=/console/ npx vite build → 部署 A/B 静态层 → 真机验收
```
```bash
# 你产 patch 的建议命令（只含你的路径）
git add web/src/pages/ecommerce
git diff --cached > /tmp/ecom-YYYYMMDD.patch
git diff -- web/src/router.tsx web/src/services > /tmp/ecom-shared-YYYYMMDD.patch   # 共享文件单独给
```
> 本仓库 `origin` 是**公开上游**（`github.com/basketikun/infinite-canvas`），**不是**我们的发布通道 → 不要 push，也不要拿它覆盖生产文件。

---

## 8. 禁止清单（命令级；**你有 root，但请一条都别做**）

```bash
# 🚫 任何理由都不要执行
rm -rf /usr/xc/*                                   # 生产资产
cp|mv|rsync|tar ... /usr/xc/tomcat-console-a/webapps/console/     # 覆盖线上前端
cp|mv|rsync|tar ... /usr/xc/tomcat-console-b/webapps/console/
vi|sed|echo > /usr/xc/aiconsole-src/**/*.java
sh /usr/xc/compile_*.sh                            # 重编后端（线上 class ≠ 源码，会降级）
sh /usr/xc/sync_ab_classes.sh
sh /usr/xc/deploy_restart.sh                       # 滚动重启生产（会打断长任务）
systemctl restart|stop|start <任何单元>
nginx -s reload / 改 /etc/nginx/**
mysql -e "DROP|DELETE|UPDATE|ALTER|TRUNCATE ... ai_console.*"
mysql -e "... 其它任何库"
crontab -e / 写 /etc/cron.d/**
git push origin / git push --force
对 https://mutual-integrity.com/console/api/** 做批量/压测/爬取
```

**允许**：在 `/home/ecom/**` 里增删改、装依赖、构建、起你自己的服务、用 `ecom_dev`、看自己的日志。

---

## 9. 出事了怎么恢复（**先停手，再执行**）

> 2026-09-21 已做好还原点：`/usr/xc/snapshots/pre-ecom-20260921/`（含前端产物、A 的 `WEB-INF/classes` 打包、
> nginx 配置打包、**一份命名保留的数据库全量备份** `pre-ecom-ai_console.sql.gz`、以及基线 `baseline.txt`）。

| 你动坏了什么 | 恢复动作 |
|---|---|
| **主站前端**（`/console/` 白屏/旧包） | `cd /usr/xc/snapshots/pre-ecom-20260921 && cp console-a-index.html /usr/xc/tomcat-console-a/webapps/console/index.html`，A/B 两个实例都做一遍；assets 目录可用 `ls /usr/xc/tomcat-console-a/webapps/console/assets_bak_20260921_*` 里的快照回滚 |
| **后端 class**（编译/替换过） | `tar -xzf /usr/xc/snapshots/pre-ecom-20260921/classes-a.tar.gz -C /usr/xc/tomcat-console-a/webapps/console/WEB-INF/` → `sh /usr/xc/sync_ab_classes.sh` → **找平台侧**确认后再滚动重启 |
| **nginx 配置** | `tar -xzf /usr/xc/snapshots/pre-ecom-20260921/nginx-conf-d.tar.gz -C /etc/nginx` → `nginx -t` → `nginx -s reload` |
| **数据库**（误删/误改 `ai_console`） | 立即停止写入并通知平台侧；还原点：`/usr/xc/snapshots/pre-ecom-20260921/pre-ecom-ai_console.sql.gz`（另有每日备份 `/usr/xc/backup/ai_console_YYYY-MM-DD.sql.gz`，保留 3 天） |
| **不确定** | 先跑 `sh /usr/xc/snapshots/pre-ecom-20260921/guard.sh` 看差异，再联系人；**不要继续操作** |

自检脚本（改动前后各跑一次，输出贴给平台侧）：

```bash
sh /usr/xc/snapshots/pre-ecom-20260921/guard.sh
# 关注：bundle 名 / class md5+字节数 / jiuxiao.conf md5 / healthz / 公网 200
```

---

## 10. 每次改完的自检清单（把结果贴给平台侧）

- [ ] `https://ecom.mutual-integrity.com/` 返回 200，`#/ecommerce` 功能卡渲染正常、**Console 0 报错**
- [ ] 构建用的是 `VITE_BASE=/`（不是 `/console/`）
- [ ] 用**自己的测试账号**跑通一条最小生成（给出任务 id / 截图）
- [ ] 没有写 `/usr/xc/**`、`/etc/**`、`ai_console`、别人的库（`guard.sh` 输出为证）
- [ ] 改动清单：哪些文件、哪些是**共享文件**、是否需要后端
- [ ] `/home/ecom` 占用 < 1GB
- [ ] 如需上生产：已产出只含 `web/src/pages/ecommerce/**` 的 patch

---

## 11. 升级路径

- 对接人：**薛诚**（平台侧）。**生产发布、nginx、后端编译、数据库、证书、cron 一律由平台侧执行。**
- 你的智能体在以下情形**必须先问人**：涉及 `/usr/xc`、`/etc`、systemd、非 `ecom_dev` 的库、证书、cron、
  `git push origin`、以及任何"清除/重置/重启/重编"类操作。

---

## 附：可直接粘给你智能体的开场约束（复制这段）

```
你在为一台共享的生产服务器工作：同一台机器上跑着「云创 AI 控制台」生产站和其它几个模块。
你有 root，但这不代表可以动它们。你的活动范围：/home/ecom/**（代码与产物）、ecom_dev 数据库、端口 5199 起的自有服务。
硬性禁止：写 /usr/xc/tomcat-console-a|b/webapps/console/**；写 /usr/xc/aiconsole-src/**；
跑 /usr/xc/compile_*.sh、sync_ab_classes.sh、deploy_restart.sh；改 /etc/nginx/** 或 reload nginx；
重启任何 systemd 服务；碰 ai_console 或任何非 ecom_dev 的库；写 cron；git push origin。
（特别提醒：线上 ScriptBenchServlet.class 与源码不一致，用源码重编会降级线上功能。）
你的测试页：https://ecom.mutual-integrity.com/ ；构建必须 VITE_BASE=/ 并输出到 /home/ecom/dist。
测试页的生成是真实调用、真扣积分：只用你自己的测试账号，不做批量/压测，测试数据加「临时-ecom」前缀并清理。
发布到主站 /console/ 不由你做：产出只含 web/src/pages/ecommerce/** 的 patch 交平台侧。
每次改动前后各跑一次：sh /usr/xc/snapshots/pre-ecom-20260921/guard.sh
任何"清除/重置/重启/重编/提权"类操作，先停下来问人。
```