# Star Office UI 更新文档（P0 / P1）

更新时间：2026-03-04
分支：`feat/office-art-rebuild`

---

## 1. 更新目标

本轮更新目标分为两层：

- **P0：安全与可发布性**（防泄漏、防弱配置、上线前可自检）
- **P1：结构与稳定性优化**（不减功能、提升状态同步与加载体验）

同时处理了线上关键问题：

- 服务偶发 502（进程/服务启动方式不稳定）
- 角色状态与真实工作状态不一致（尤其“回复结束仍在工位”）

---

## 2. P0 已完成项

### 2.1 后端安全基线加固

- 增加生产模式安全校验（弱密钥/弱口令阻止启动）
- Session Cookie 安全参数加固（HttpOnly / SameSite / Secure）
- `runtime-config.json` 写入后自动尝试收紧文件权限（`600`）

### 2.2 敏感文件治理

- `.gitignore` 补充运行态文件与高风险文件
- 引入样例文件替代运行态文件：
  - `join-keys.sample.json`
  - `.env.example`
- `join-keys.json` 改为运行时初始化，不再作为仓库内固定配置

### 2.3 上线前安全自检能力

- 新增 `scripts/security_check.py`
- 可检查：
  - 弱 secret / 弱口令
  - 风险文件是否被 git 跟踪
  - 常见敏感 token 模式

---

## 3. P1 已完成项（不改业务能力）

### 3.1 后端结构拆分

在不改变现有 API 行为前提下，把 `backend/app.py` 拆出：

- `backend/security_utils.py`
- `backend/memo_utils.py`
- `backend/store_utils.py`

收益：
- 降低单文件复杂度
- 降低后续功能改动时的回归风险
- 提升可读性与维护效率

### 3.2 状态同步修复（核心）

- 修复状态源路径优先级（避免读取错误状态文件）
- 增加 stale 状态自动回 `idle` 机制（避免假工作中）
- 前端状态轮询改为更快节奏并强制视觉对齐，避免动画卡旧状态

### 3.3 生图模型策略收敛

按需求收敛为两种用户模型语义：

- `nanobanana-pro`
- `nanobanana-2`

并补充 provider 映射与错误细节透出，提升可诊断性。

### 3.4 首屏性能与体感优化

- 首页 HTML 缓存（后端进程内缓存）
- 非关键初始化延后（先出画面）
- 加入画布骨架屏，减少“黑屏 + 长时间加载中”体感
- 加速 loading overlay 淡出

---

## 4. 线上稳定性修复（本轮重点）

### 4.1 502 根因

Cloudflare 正常，但 `18888` 源站进程存在不稳定/启动方式不一致，导致偶发 connection refused。

### 4.2 已处理

- 修复并统一 `star-office-ui.service` 启动方式（systemd 常驻）
- 清理手工临时启动造成的端口抢占
- 重启并验证：
  - `star-office-ui.service` 运行正常
  - `star-office-push.service` 运行正常

---

## 5. 当前已知风险 / 待跟进

1. **状态策略仍需完全事件化**
   - 目前已大幅收敛误判，但建议后续做单一状态控制器（显式事件优先，彻底禁用隐式推断）

2. **进程模型仍是 Flask 开发服务器**
   - 当前可用但不理想，后续建议迁移为 gunicorn/uvicorn 等生产进程模型

3. **动画状态同步仍建议增加端到端回归脚本**
   - 尤其 writing / syncing / error / idle 切换链路

---

## 6. 验收建议（人工）

验收地址：`https://simonoffice.hyacinth.im/`

建议至少覆盖：

1. 首页进入速度与骨架屏体验
2. 状态切换（writing / syncing / error / idle）
3. 回复结束后是否回到待命区
4. 生图两入口（搬新家 / 找中介）
5. 断网或服务短时波动后是否自动恢复

---

## 7. 提交范围（摘要）

本轮主要覆盖：

- 安全与配置：P0
- 后端重构：P1
- 状态同步与动画一致性修复
- 生图模型策略与错误诊断
- 加载性能与体验优化
- systemd 常驻与稳定性修复

如需 PR 附件，可直接将本文件作为“更新说明 / Release Notes”。