xmz7891
de5018bbbe
用户定的规矩：
只修 bug -> 最后一位 +1 1.8.2 -> 1.8.3
加新内容/重构 -> 第二位 +1，最后一位清 0 1.8.2 -> 1.9.0
这一轮既有新东西（设置窗口的中转服务器字段、允许新设备接入开关、
双击开设置窗口）又有重构（手表面板切换收成 showOnly()），
所以是 **1.9.0**，不是我之前说的 1.8.3。
== 顺手加了个「版本号一致性」检查（回归阶段 3a8）==
版本号散落在 8 个地方，靠脚本+人工替换很容易漏。实测漏了两个，
而且**漏了不报错**，只是用户看到一个对不上的版本号：
* windows/version_info.txt 写着 1.7.1
-> 用户在「文件属性 -> 详细信息」里看到的版本，错了三个版本
* docs/LICENSE.txt 写着 1.7.1
-> 安装时许可页上显示 1.7.1
第二个的根因值得记：installer/build_installer.py 会从 docs/ 里三份
文档**重新生成** license-combined.txt，所以光改生成物没用 ——
下次构建又变回去（我第一次就是这么被骗的）。改成在 build_license()
里**统一注入当前版本**，源文档写什么都不影响。
新增：
_tests/check_version_consistency.py 检查 8 处版本号一致
_build/add_verify_stage.py 给套件加阶段（不经 shell，
不会被 PowerShell 吃掉 \$ 变量）
_build/fix_license_version.py 按行精确修 license
== 另外修了两个我自己的坑 ==
1. verify_all.ps1 被 PowerShell heredoc 吃掉了 \ / \，
整个脚本语法错。**同一个坑踩了两次**（3a7 和 3a8）。
以后给 .ps1 加含 \$ 的内容一律写 Python 脚本文件再跑。
2. build_exe.ps1 被 edit 工具吃掉了 UTF-8 BOM
（PowerShell 5.1 会按 GBK 读，中文注释乱码）。
全量回归 43 个阶段全部通过。
5.4 KiB
项目规矩（每次改动都要遵守）
这份文件是给开发和发布看的硬性约束。新会话接手时先读这个。
一、发布流程：先给用户，用户验完才推送
用户原话：「你以后就这样，你先把所有东西给我，我运行没问题再告诉你帮我推送」
每次发版必须按这个顺序：
- 本地把所有产物构建完成
- 跑测试（全量回归 + 安装包周期 + 发布验收）
- 把产物交给用户去验证
- 等用户明确说「可以推」之后，才创建 Gitee 发布 / 上传发布附件
❌ 绝对不能自己构建完就直接建发布。
✅ 代码提交到 main 是可以的（那不是"发布"）。
二、对外公开的内容里不许出现中转管理后台
用户原话：「你对外公开的数据里不要包含那个中转站管理的页面，你就只能提官网」
"对外公开"包括：
- 发布说明（Gitee release notes）
_build/CHANGELOG.md（它会变成发布说明）- 官网页面（
relay/landing.py渲染出来的） README.md- 我（AI）在对话里给出的总结、汇报、方案
- 任何我会贴给用户看、或用户可能转给别人的材料
只能提官网 https://relay.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 换掉。
版本号散落在多处，用脚本统一改：
python _build\bump_180.py # 改版本号时把里面的 OLD/NEW 改掉
⚠️ .ps1 文件必须保留 UTF-8 BOM，否则 PowerShell 按 GBK 读会中文乱码 + 语法报错。
用 edit 工具改 .ps1 会吃掉 BOM，改完要补：
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）。
七、改完必须立刻验
这一天里我因为"改完没验"翻了三次车：
- 替换管理页时把
main()入口一起删了 → relay 起不来，systemd 重启 24 次， 所有接口 000。教训："删到文件末尾"之前必须先确认末尾有什么。 - 引用了从没定义过的
ADMIN_PATH常量 → 管理页 NameError。 - 改了
_send()的调用没传 Content-Type → 浏览器把整页 HTML 当纯文本显示。当时只验了 HTTP 200 和字节数，两个都对。 → 200 不等于页面能看，响应头也得看。
规矩：任何改动之后，至少跑一遍 「管理页 + 官网 + 关键接口 + 响应头」的回归。
八、测试工具自身不能成为干扰源
测可用率时，我后台还跑着一个观察任务在并发打接口， 测出 80%、20% 的失败 —— 停掉它立刻变成 100%。
测稳定性之前，先确认没有别的任务在打同一个接口。