# 项目规矩（每次改动都要遵守）

> 这份文件是给**开发和发布**看的硬性约束。新会话接手时先读这个。

---

## 一、发布流程：按「预案」执行

> 用户原话：「以后我会说按照预案几处理」
>
> 用户原话（预案一）：「做完以后测试，没问题上传」
> 用户原话（预案二）：「做完以后测试，测试完以后别上传，直接给我」

**用户会明确说"按预案几"，说了就按那个走。**

| 预案 | 做什么 |
|---|---|
| **预案一** | 做完 → **测试** → 没问题 → **上传**（创建 Gitee 发布 + 传附件 + 部署到服务器） |
| **预案二** | 做完 → **测试** → **不上传**，产物交给用户 |

### 两个预案共同的部分（都必须做）

1. 本地把**所有产物**构建完成（APK / 安装包 / 服务端包）
2. 跑测试：全量回归 + 安装包周期 + 发布验收
3. **测试不绿就停**，先说清楚哪儿红了 —— 不许带着红测试交付

### 只有预案一才做的部分

4. 提交 `main` + 推送
5. 创建 Gitee 发布、上传三个附件
6. 部署到服务器（`_build/deploy_lightsail_release.py`），并**实测**线上：

   - `/v1/update/latest` 返回的版本 = 刚发的
   - 官网角标 = 刚发的
   - 安装包能下（看真实字节数）
   - `/v1/health` 正常

### 用户没说预案几的时候

**默认按预案一**（那是长期以来的既有习惯），但要在交付时**说明**
"我按预案一做了，已经上传"，让用户有机会纠正。

### 历史（这条规矩怎么来的）

最早用户说「你先把所有东西给我，我运行没问题再告诉你帮我推送」，
中间放宽过一次（「你自己上传就行了」），后来又要"自己测完再上传"。
现在固化成两个预案，由用户每次指定。

**仍然绝对不做的**：不测就上传。

---

## 二、对外公开的内容里**不许出现中转管理后台**

> 用户原话：「你对外公开的数据里不要包含那个中转站管理的页面，你就只能提官网」

**"对外公开"包括：**

- 发布说明（Gitee release notes）
- `_build/CHANGELOG.md`（它会变成发布说明）
- 官网页面（`relay/landing.py` 渲染出来的）
- `README.md`
- **我（AI）在对话里给出的总结、汇报、方案**
- 任何我会贴给用户看、或用户可能转给别人的材料

**只能提官网 `https://yk.xxmxxs.top`。**

**不要说**：`/zhongzhuanzhan`、`/admin`、"管理后台"、"管理页"、
"管理入口"、管理密码之类。

### 边界（用户已确认）

| 范围 | 要不要清理 |
|---|---|
| 发布说明 / 更新日志 / 官网 / README / 我的对外汇报 | ✅ **必须清理** |
| 服务端 zip 里的运维文档（`README-server.txt`、`AFTER-INSTALL.txt` 等） | ❌ **保留** —— 那是给装服务器的人看的，删了他不知道怎么运维 |
| 仓库源码里的实现（`relay/relay.py` 等） | ❌ **保留** —— 路径是功能本身，藏起来没法维护 |
| `_build/` 里的一次性脚本、`_tests/` | ❌ 保留（内部工程材料） |

### 换一种说法

需要提到"能看设备列表 / 删设备 / 看流量"这类能力时，说：

> 「在官网下载，需要管理时看服务端 zip 里的说明文档」

不要直接把管理页摆出来。

---

## 三、发版必须更新版本号

> 用户原话：「自行更新版号」
> 后来又补了怎么加的规定（见下表）

每次上传都要升版本号。**怎么加按改动性质定**：

| 改动性质 | 怎么加 | 例子 |
|---|---|---|
| **只修 bug** | 最后一位 +1 | 1.8.2 → **1.8.3** |
| **加了新内容 / 重构** | 第二位 +1，**最后一位清 0** | 1.8.2 → **1.9.0** |

⚠️ **一轮里只要同时有"新东西"和"修 bug"，就按新东西算**（升第二位）。
比如某一轮既加了设置窗口的中转服务器字段（新功能）、
又把面板切换重构成 `showOnly()`（重构）、还修了 502（bug）——
那就是 **1.9.0**，不是 1.8.3。

**为什么这条重要**：下载站是按 URL 缓存的
（`/download/ykxmz-setup-1.8.2.exe` 带 `max-age=604800, immutable`）。
**内容变了但不换 URL，缓存就会失效一次** —— 实测重新打包 server.zip
之后第一次请求 `cf-cache-status=MISS`。升版本号正好把 URL 换掉。

版本号散落在多处，**用脚本统一改**：

```powershell
python _build\bump_180.py   # 改版本号时把里面的 OLD/NEW 改掉
```

⚠️ `.ps1` 文件必须保留 **UTF-8 BOM**，否则 PowerShell 按 GBK 读会中文乱码 + 语法报错。
用 `edit` 工具改 `.ps1` 会吃掉 BOM，改完要补：

```powershell
python _build\fix_ps1_bom.py
```

---

## 四、发布产物的组成

| 平台 | 产物 | 说明 |
|---|---|---|
| Windows | `ykxmz-setup-X.Y.Z.exe` | **安装包**，不是 agent zip。用户要双击就能装 |
| 服务端 | `ykxmz-server-X.Y.Z.zip` | 随身 WiFi / Linux |
| 手表 | `ykxmz-watch-X.Y.Z.apk` | 直接给 APK，不打 zip |

**发布说明只放更新内容**（用户原话：「以后只放更新内容」），不要放安装教程之类的。

---

## 五、README 只在功能变化时更新

> 用户原话：「以后只放更新内容」/ 修 bug 不用动 README

功能变了才更新 `README.md`；纯 bug 修复不用。

---

## 六、设计理念：白色简洁

> 用户原话：「所有东西都要白色简洁，这是我的设计理念」

官网、管理后台、文档、任何界面 —— 一律白色、简洁、克制。
配色令牌见 `relay/landing.py` 顶部（`#ffffff` / `#fafbfc` / `#e6e8eb` /
`#1a1d21` / `#6b7280` / `#2563eb`）。

---

## 七、改完必须立刻验

这一天里我因为"改完没验"翻了三次车：

1. 替换管理页时**把 `main()` 入口一起删了** → relay 起不来，systemd 重启 24 次，
   所有接口 000。教训：**"删到文件末尾"之前必须先确认末尾有什么。**
2. 引用了**从没定义过的 `ADMIN_PATH` 常量** → 管理页 NameError。
3. 改了 `_send()` 的调用**没传 Content-Type** → 浏览器把整页 HTML
   当纯文本显示。**当时只验了 HTTP 200 和字节数，两个都对。**
   → **200 不等于页面能看，响应头也得看。**

**规矩**：任何改动之后，至少跑一遍
「管理页 + 官网 + 关键接口 + 响应头」的回归。

---

## 八、测试工具自身不能成为干扰源

测可用率时，我后台还跑着一个观察任务在并发打接口，
测出 80%、20% 的失败 —— 停掉它立刻变成 100%。

**测稳定性之前，先确认没有别的任务在打同一个接口。**