mirror of
https://gitee.com/xmz7891/ykxmz.git
synced 2026-10-18 12:30:44 +00:00
xmz7891
fd8be87209
用户这一轮报了两个问题，都修了。
== 一、Win7 上语音播报不能用 ==
用户原话："我 win7 上的语音播报好像不能用，你再试一下别的版本能不能用"
**原来只有一条路**：
powershell -NoProfile -WindowStyle Hidden -Command
"Add-Type -AssemblyName System.Speech; $s = New-Object ...; $s.Speak('...')"
这在 Win7 上有三个坑，任何一个都能让它彻底不出声：
1. **`powershell` 只按名字找**
Win7 的 powershell.exe 在 `%SystemRoot%\System32\WindowsPowerShell\v1.0\`。
精简版系统、或从服务/计划任务拉起时 PATH 里可能没有 ——
CreateProcess 按名字找不到时是**静默失败**的。
2. **Win7 默认 PowerShell 2.0，它按 ANSI 代码页解析 `-Command`**
PS 3.0 起才按 UTF-16 处理。中文经 `-Command` 传进去容易乱码 ——
表现是念出来是乱码，或者干脆不念。
3. **`System.Speech` 需要 .NET Framework 3.0+**
而系统自带的 **SAPI5** 从 Windows XP 就有，**根本不需要 .NET**。
**改成多方案降级**，按"依赖越少越优先"排：
1. cscript + VBScript + SAPI5 <- Win98 起就有，不用装任何东西
2. wscript + VBScript + SAPI5 <- 上一条被安全软件拦时的备选
3. powershell + SAPI5 (COM) <- 绕开 .NET
4. powershell + System.Speech <- 原来的做法，改用绝对路径
5. powershell(PATH) + System.Speech <- 最原始的，兜底
一条通了**记住它**，以后直接用（不用每次从头试）。
**顺带修掉一个"骗人"的行为**：原来 `say()` 用 `Popen` 不等进程结束，
失败了也返回"已播报" —— 明明没出声却报成功。
现在等退出码，**全失败会明确报错并列出试过哪几条**。
代价是同步等待（念多久等多久），但"报成功其实没出声"比"慢一点"糟糕得多。
还加了 `_build/diag_tts.py`：在一台机器上把 5 条方案全试一遍并报告
哪条能用 —— 下次再有"某台机器上不行"，跑一下就知道。
VBScript 的细节：**必须用 ANSI(mbcs) 写**，写成 UTF-8 的话
cscript 读出来中文是乱码（VBScript 的老规矩，很隐蔽）。
长文本还要分句 —— VBScript 单行有长度上限。
== 二、快捷栏按钮太小 + 4 格都要能换 ==
用户原话："屏幕最上面这个按钮有些按不到，按钮太小了，做大一点，
然后呢，这个每每个四格算换一下吧，第一个第二个第三个
第四个都能换东西"
* **按钮做大**：30dp -> 46dp（接近 Android 建议的最小可点区域 48），
字号 11 -> 14。30dp 在表盘上手指按上去一半在栏外。
**栏高做成常量 QUICK_BAR_DP，栏高 / 面板 topMargin / addView
三处用同一个值** —— 分三处写的话改一个忘一个，
表现是"内容被盖住"或"上面空一条"。
* **4 格全部可自定义**。用户最早说"其中有一个按钮不能改，
功能就是一键返回桌面"，第一版就按"第 4 格写死 desktop"做的。
现在他改主意了 —— 所以 desktop 变成**普通可选动作**，
默认仍放第 4 格（习惯不用改），但想换也能换。
可选动作从 7 个变成 8 个。
**教训（写进测试注释了）**：别把"用户当时的一句话"当成永久约束
焊进结构里；真是约束的话，注释里要写清是什么时候的要求，
下次他改主意时才知道该动哪儿。
== 三、修一个"测试自己没擦干净"造成的假 bug ==
全量回归报：
[FAIL] 配对码正确写入 实际 '（旧的残留值）'
而 `（旧的残留值）` 是**上一次测试遗留**的配对码 —— 数据目录
`C:\ProgramData\ykxmz\data` 在卸载时**故意不删**（那里存着用户的
中转地址、配对码等，卸载不该删），所以机器上会留着上一轮的
settings.json。测试装的时候虽然传了 `/CODE=517284`，但环境没擦干净时
就可能读到旧值 —— 表现成"安装包有 bug"。
**修法**：`test_installer_cycle.py` 加一步"装前先清残留"
（正规卸载 -> 杀进程 -> 删安装目录 -> **删数据目录**）。
数据目录那一步是关键 —— 卸载器不删它。
== 四、其他 ==
* `docs/项目规矩.md` 第一节改成**按预案执行**：
预案一 = 做完测试没问题就上传；预案二 = 做完测试但不上传，直接给用户。
用户没说预案几时默认按预案一，并在交付时说明。
* 顺手把那份文档里的老域名 `relay.xxmxxs.top` 改成现在的
`yk.xxmxxs.top`（老服务器早就退役了）。
* 修掉自己造的重复定义：往 actions.py 插降级链时，
`list_voices` / `say` 各插了两份（pyflakes 报 redefinition）。
* 一次危险的误操作：`Path.write_text(..., newline='\n')` 会**先截断文件
再校验参数**，参数非法时文件已经空了 —— 我用它把
`_tests/test_quickbar.py` 清空了。已重写。
**以后不给 write_text 传 newline。**
== 验证 ==
全量回归（21 关）全部 PASS
新增关卡：3a13 手表快捷栏 / 3a14 语音播报降级
安装包周期 23 项全过（装 -> 验 -> 卸 -> 再验）
Java 编译通过（android-34, --release 8）
本机实测语音播报：cscript 那条通了（2.4 秒）
全部产物重建，Win7 兼容校验通过
179 lines
6.5 KiB
Markdown
179 lines
6.5 KiB
Markdown
# 项目规矩（每次改动都要遵守）
|
||
|
||
> 这份文件是给**开发和发布**看的硬性约束。新会话接手时先读这个。
|
||
|
||
---
|
||
|
||
## 一、发布流程：按「预案」执行
|
||
|
||
> 用户原话：「以后我会说按照预案几处理」
|
||
>
|
||
> 用户原话（预案一）：「做完以后测试，没问题上传」
|
||
> 用户原话（预案二）：「做完以后测试，测试完以后别上传，直接给我」
|
||
|
||
**用户会明确说"按预案几"，说了就按那个走。**
|
||
|
||
| 预案 | 做什么 |
|
||
|---|---|
|
||
| **预案一** | 做完 → **测试** → 没问题 → **上传**（创建 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%。
|
||
|
||
**测稳定性之前，先确认没有别的任务在打同一个接口。**
|