Recognize local app states (T-202)

docs/api.md

@@ -138,6 +138,41 @@ T-102 Phase 1 原型进一步固定:
 
 记录实际安装的软件 ID、版本、架构、channel 和文件清单;与 `current/`、`staging/`、`backup/` 同级存放于 `apps/<id>/`。
 
+```json
+{
+  "schema_version": 1,
+  "id": "json-parser",
+  "version": "1.4.2",
+  "architecture": "amd64",
+  "channel": "stable",
+  "files": [
+    {
+      "path": "JsonParser.exe",
+      "size": 3456789,
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  ]
+}
+```
+
+规则:
+
+- Schema 位于 `schemas/installed-app.schema.json`;未知字段、非法 SemVer、ID/目录不匹配、非 `386|amd64` 架构、非 stable channel、安全相对路径以外的文件名、重复路径和非法 SHA-256 均拒绝。
+- `files` 必须是数组;v1 可以为空,完整文件清单由 T-302 安装整合时从已验证包写入。
+- 写入使用 app 目录内临时文件 + `installed-app.json.backup` 原子替换;主文件缺失时可读取中断遗留 backup,但所有读取都重新严格校验。
+- SemVer 比较遵循 2.0.0:major/minor/patch 与 prerelease 参与 precedence,build metadata 不影响更新判断。
+
+### 2.4.1 本地可见状态推导
+
+状态事实由后台/存储层预先收集,UI Layout 不扫描磁盘。单一可见状态按以下优先级推导:
+
+1. 存在 `install-transaction.json` 或其 backup → `rollback_pending`。
+2. 存在活跃任务状态 → `queued|downloading|verifying|extracting|installing|failed`。
+3. 已检测到进程运行 → `running`。
+4. Catalog 判定不可兼容 → `incompatible`。
+5. 无 installed-app.json → `not_installed`。
+6. 本地 SemVer 低于 Catalog → `update_available`;否则 → `installed`。Catalog 中已隐藏/下架且无可比较版本时,保留 `installed`。
+
 ### 2.5 安装切换事务(Phase 1 原型)
 
 `apps/<id>/install-transaction.json` 用于断电恢复: