chore: 整理项目结构，清理归档文件，更新部署配置

2026-07-04 21:01:39 +08:00
parent 8bd4ab0366
commit 64ff1bf7d5
508 changed files with 43575 additions and 14129 deletions
@@ -0,0 +1,226 @@
+# 需求: 应急降级页(H5 + Agent Preview)via 企微"服务窗口"
+
+**需求提出**: 2026-06-15(经多次澄清,核心场景为 BC/DR)
+**需求方**: Simon
+**核心场景**: 🔴 **业务连续性(BC/DR)** — 系统故障时切换至企微原生服务,坐席保留关键功能
+**入口**: 🏢 **企微"员工服务"应用 → "服务窗口"**(只配 1 个 URL)
+**关联规则**: [[locked-decisions]] § 应急降级 / [[preview-pages-sync-rule]]
+
+---
+
+## 🎯 业务目标(真实场景)
+
+当本系统出现**特殊情况**(故障 / 不可用 / 合规要求 / 流量过载)时:
+
+1. **员工侧**: 切换至企微**原生员工服务**(群聊/单聊兜底)
+2. **坐席侧**: 通过企微"员工服务 → 服务窗口" 链接,使用本系统应急页
+3. **目标**: 即使主系统挂掉,**核心 IT 服务不中断**
+
+## 🏢 入口架构(1 URL + 企微 JS-SDK)
+
+```
+┌────────────────────────────────────────┐
+│  企微"员工服务"应用(企业已建)            │
+│  └─ "服务窗口" tab(只能配 1 个 URL)     │
+│     └─ https://itsupport.servyou.com.cn/emergency
+└────────────────────────────────────────┘
+              ↓
+┌────────────────────────────────────────┐
+│  /emergency 页面(身份检测)              │
+│  1. 加载企微 JS-SDK(不依赖本后端)       │
+│  2. agentConfig 拿当前 userid            │
+│  3. 调企微通讯录 API 查 user 详情        │
+│  4. 判断身份:是"IT支持-咨询坐席"标签成员 │
+│     ├─ 是 → router.push('/agent/preview')│
+│     └─ 否 → router.push('/h5/preview')  │
+└────────────────────────────────────────┘
+```
+
+**关键**:
+- 身份检测**不依赖本系统后端**(主系统挂时仍可用)
+- 应急页 2 套(h5 + agent),通过 router.push 切换
+- 企微通讯录 API 走企微 access_token,跟主系统无关
+
+## 📋 保留功能(4 件套 + 动态联系人)
+
+| # | 功能 | 描述 | 数据源 |
+|---|---|---|---|
+| 1 | 🔍 **快速回复模板** | 100+ 条按关键词搜索 | mock JSON → localStorage |
+| 2 | 🔍 **排障流程模板** | vpn/邮箱/系统/账号 4 大类 | mock JSON → localStorage |
+| 3 | 📋 **资源/审批链接** | 12 个常用入口 | mock JSON → localStorage |
+| 4 | 👥 **应急联系人** | 企微标签"IT支持-咨询坐席"成员 | 企微 API → 单独 localStorage |
+| **合计** | | | **~750KB + 联系人列表** |
+
+### 应急联系人(动态,非固定)
+
+**数据源**: 企微通讯录标签"IT支持-咨询坐席"
+
+**预同步**:
+- 主系统正常时,每 30 分钟调企微通讯录 API 查该标签成员
+- 存到**独立 localStorage key** `emergency_contacts`:
+  ```json
+  {
+    "synced_at": "2026-06-15T10:00:00",
+    "tag_id": "TAG_xxx",
+    "members": [
+      {"userid": "zhangsan", "name": "张三", "avatar": "...", "online": true},
+      ...
+    ]
+  }
+  ```
+
+**应急展示**:
+- 列出标签下所有成员
+- 在线/离线状态(企微 status 接口)
+- 点击 → 打开企微单聊
+- 数据 > 1 小时未更新时标红,提示"联系人可能不准,建议手动搜索标签组"
+
+## 🆘 "特殊情况" 触发与降级
+
+| 类型 | 触发条件 | 降级动作 |
+|---|---|---|
+| 🔴 主系统完全不可用 | API 5xx / 网络断开 | 切企微原生 + 服务窗口 |
+| 🟡 部分功能故障 | 消息发送失败 / 排队堵死 | 切企微原生 + 工具走应急页 |
+| 🟠 合规要求 | 必须用企微审计 | 切企微原生 + 应急页工单 |
+| 🟢 流量过载 | 服务降级中 | 部分功能走应急页 |
+
+## 📋 范围
+
+| 项 | H5 应急页 | Agent 应急页 |
+|---|---|---|
+| URL | `/h5/preview` | `/agent/preview` |
+| 统一入口 | `/emergency` | `/emergency` |
+| 显示组件 | `RightPanel.vue`(3 段式) | `AiAssistantPanel.vue`(4 件套) |
+| 去除功能 | `ChatPanel`(聊天走企微原生) | `ConversationList` + `ChatArea` + `TopBar` |
+| 数据源 | **预同步到 localStorage** | **预同步到 localStorage** |
+| 后端调用 | **无**(主系统可能挂) | **无** |
+| 用户登录 | **跳过**(应急场景免登) | **跳过**(应急场景免登) |
+
+## 🔄 数据预同步机制(2 个独立 localStorage)
+
+### localStorage #1: `emergency_data`(静态工具数据)
+
+**正常态**:
+```
+主后端 /api/emergency-data 
+    → 前端每 30 分钟拉取
+    → 存到 localStorage("emergency_data")
+```
+
+**应急态**:
+```
+localStorage("emergency_data") → 应急页直接渲染
+```
+
+**内容**: 快速回复 / 排障 / 资源(~750KB)
+
+### localStorage #2: `emergency_contacts`(动态联系人)
+
+**正常态**:
+```
+企微通讯录 API 查"IT支持-咨询坐席"标签
+    → 前端每 30 分钟拉取
+    → 存到 localStorage("emergency_contacts")
+```
+
+**应急态**:
+```
+localStorage("emergency_contacts") → 应急页渲染联系人列表
+```
+
+**内容**: 标签成员列表(动态,可能多人)
+
+## 🎨 页面要求(应急场景)
+
+### `/emergency`(身份检测入口,~50 行)
+
+- 加载企微 JS-SDK(wx.config + wx.agentConfig)
+- 拿当前 userid
+- 调企微通讯录 API 查 user 详情 + 标签
+- 判断是否含"IT支持-咨询坐席"标签
+- 是坐席 → push /agent/preview,否则 → push /h5/preview
+- 检测失败 → 显示"请选择身份"2 个大按钮兜底
+
+### H5 应急页(`/h5/preview`)
+
+- 顶部: 项目名 + **"🆘 应急模式"** 红色徽章 + 数据更新时间
+- 主体: `RightPanel` 全宽,3 段式(AI 推送 / 资源 / 趣味问答)
+- 底部: 固定"主系统异常?此页面帮您继续获得服务"
+- 移动端: 强制显示(覆盖 `isMobile` 判断)
+
+### Agent 应急页(`/agent/preview`)
+
+- 顶栏: 简化版 TopBar + 🆘 徽章
+- 主体: `AiAssistantPanel` 全宽,4 件套
+- 联系人: 标签组成员 + 在线状态
+- 底部: 固定"主系统异常"提示
+
+## 📁 文件改动清单(调整)
+
+### H5 端 (frontend-h5/)
+
+| 操作 | 路径 | 说明 |
+|---|---|---|
+| 新建 | `src/views/EmergencyEntry.vue` | 身份检测入口(~50 行) |
+| 新建 | `src/views/H5PreviewView.vue` | 应急主页 |
+| 新建 | `src/mock/emergency-data.json` | 应急静态数据 |
+| 新建 | `src/utils/emergency-sync.ts` | 同步工具(2 个 localStorage) |
+| 改 | `src/router/index.ts` | 加 `/emergency` + `/h5/preview` |
+| **复用** | `src/components/assistant/RightPanel.vue` | import 共享 |
+
+### Agent 端 (frontend-agent/)
+
+| 操作 | 路径 | 说明 |
+|---|---|---|
+| 新建 | `src/views/AgentPreviewView.vue` | 应急主页 |
+| 改 | `src/router/index.ts` | 加 `/agent/preview` |
+| **复用** | `src/components/assistant/AiAssistantPanel.vue` | import 共享 |
+
+**注**: 联系人 API 调用放 `emergency-sync.ts` 共用模块,h5 + agent 都用
+
+## 🧪 验收标准
+
+### 功能验收
+
+- [ ] **断网测试**: 拔网线/关后端 → 应急页仍能打开
+- [ ] **身份自动路由**: 员工点开 → /h5/preview,坐席点开 → /agent/preview
+- [ ] **联系人动态**: 标签组加新人,预同步后能显示
+- [ ] **数据新鲜度**: 顶部"数据 X 分钟前更新",> 1h 标红
+- [ ] **2 个 localStorage 独立工作**: 删 emergency_data 不影响 emergency_contacts
+
+### 灾备演练(非工作时间,本月必做)
+
+- [ ] 选择非工作时间(晚上 / 周末)
+- [ ] 模拟主系统挂掉 → 切企微原生服务 → 坐席用应急页
+- [ ] 演练时长 / 解决率 / 痛点记录
+- [ ] 详见 `docs/SOPs/SOP-005-应急降级演练.md`
+
+## 📅 排期
+
+| 时间 | 任务 |
+|---|---|
+| 2026-06-16 (周一) | WB 接单,1 入口 + 2 页面 + 1 mock + 1 同步工具 + 2 路由 |
+| 2026-06-16 (周一) | 本地 `npm run build` 验证 |
+| 2026-06-17 (周二) | 部署 + **断网演练**(非工作时间,如周二晚 20:00) |
+| 2026-06-18 (周三) | 收集问题,迭代 |
+| 2026-06-19 (周四) | 二次演练确认 |
+| 2026-06-20 (周五) | 正式版上线 + 应急页同步上线 |
+
+## ⚠️ 应急场景的额外考虑
+
+1. **入口要醒目**: 企微"员工服务 → 服务窗口"配置清晰描述
+2. **不依赖登录**: 应急时坐席可能密码都改不了,免登
+3. **非工作时间演练**: 降低对业务影响
+4. **联系人降级**: 实在没预同步数据,提示"请手动搜索 IT支持-咨询坐席 标签"
+5. **保留升级路径**: 主系统恢复后,应急页要有提示"主系统已恢复,建议返回"
+
+## 🔗 关联
+
+- **双端同步规则**: [[preview-pages-sync-rule]]
+- **锁定决策**: [[locked-decisions]] § 应急降级
+- **演练 SOP**: `docs/SOPs/SOP-005-应急降级演练.md`
+- **需求演进**: v1 灰度(误)→ v2 BC/DR(理解)→ v3 服务窗口(1 URL)→ v4 标签联系人(动态)
+
+---
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
@@ -0,0 +1,115 @@
+---
+name: v0.7.2-backlog-candidate-2026-07-04
+description: v0.7.1 开发中，基于文档优化专项后的最新状态更新
+metadata:
+  type: project
+  last_updated: 2026-07-04
+---
+
+# v0.7.2 backlog 候选(2026-07-04 更新)
+
+> **更新说明 (2026-07-04)**:
+> - v0.7.1 正在开发中（企微SSO、RBAC权限）
+> - 完成文档优化专项（用户手册创建、KPI指标补充、技术约束更新）
+> - 补充阶段四/五的KPI指标定义
+> - 新增需求：待办事项集成企微审批工单（#74）
+
+## 来源
+扫描 CURRENT-FOCUS.md(P0/P1/P2)+ phase1-progress.md 痛点 + 3 个 v1.0 必做 memory。
+
+## 🟡 候选清单
+
+### P1(可放 v0.7.2)
+
+1. **#48 [P0→P1] 收窄 /api/admin/ + /itadmin/ IP 白名单**
+   - 当前 `allow 0.0.0.0/0` 临时全开
+   - 阻塞:**需网络组确认真实代理 IP 段**(WAF/堡垒机/CDN 出口 IP)
+   - 不能 Claude 单方面定,需用户提交工单
+   - 估时:1h(改 nginx + reload + 验证)
+
+2. **#74 [P1] 待办事项集成企微审批工单**
+   - 将企微审批工单同步到坐席待办事项
+   - 需企微审批应用 API 权限
+   - 估时:2-3天
+
+3. **#73 [P1] 修后端文件未真正覆盖**
+   - `yes | cp -f` 路径,部署时偶尔没生效
+   - 根因:`deploy-staging/` bind mount + RO 双重坑(见 [[bind-mount-deleted-inode-pitfall]])
+   - 估时:2h(改 deploy 脚本用 rsync --checksum)
+
+3. **#86 [P1] 排查流程图零依赖部分 review + 文档化**
+   - 把 Mermaid 流程图从代码里剥离成可读文档
+   - 不阻塞生产,可顺手做
+   - 估时:3h
+
+4. **#92 [P1] 修 v0.7.1-dev 引入的 pytest 失败(0 引入,33 pre-existing)**
+   - 实际还有 64 个 pre-existing 失败(conftest 卡死环境问题)
+   - v0.7.1-dev 引入 0 个
+   - 估时:4h(可能是 conftest.py SQLite StaticPool 性能 + Windows + utf-8 + asyncio loop 顺序问题)
+
+### P2(可放 v0.7.3+ 或 v1.0)
+
+5. **#31 docker 镜像推生产 registry**(等用户决策 Harbor/阿里云/其他)
+6. **#43 HTTPS 证书**(等域名备案完成)
+7. **#108 Gitea push v0.7.1-dev**(等 token 重授权)
+8. **#53 企微 App 实扫码验证**(等用户手动)
+
+## 🔧 内部清理(Claude 可独立做)
+
+9. **pytest conftest 性能优化**
+   - 当前每个测试文件都要跑整套 alembic migration(从 0001 到 027)
+   - 优化:用 `alembic upgrade head` 缓存 db 到 tmpfs,或 sqlite-in-memory 复用
+   - 估时:2h
+
+10. **CURRENT-FOCUS.md 刷新到 v0.7.1 release 完成态**
+    - 当前停在 2026-06-22 19:55,看板过期 36 小时
+    - 更新 in_progress / P0 / 最近搞定段
+
+11. **pytest conftest 卡死问题根因分析**
+    - 跑单个 test_high_risk_guard.py 都 hang
+    - 怀疑 alembic migration 在 Windows + StaticPool 下死锁
+    - 估时:1h(可加 print + trace)
+
+## 📚 文档优化专项(已完成 v0.7.2)
+
+12. **✅ 05-用户手册目录创建**
+    - 已创建 3 本手册框架：员工使用指南、坐席操作手册、管理员手册
+    - 状态:已完成
+
+13. **✅ PRD KPI 指标体系补充**
+    - 新增 §4.5 指标体系详细设计
+    - 包含北极星/驱动/健康指标框架、测量方法、行业基准对比
+    - 状态:已完成
+
+14. **✅ PRD 章节编号说明**
+    - 添加版本号 v1.3 更新说明
+    - 添加章节编号解释
+    - 状态:已完成
+
+15. **✅ 技术约束状态更新**
+    - 更新约束项当前状态
+    - 补充企微设备管理付费状态
+    - 状态:已完成
+
+## 推荐 v0.7.2 范围
+
+**必含(用户能直接拍板的)**:
+- #48 IP 白名单收窄(前提:网络组确认)
+- #73 修后端文件覆盖
+- #92/9 pytest 性能 + 33 失败修复
+
+**可选(顺手)**:
+- #86 排查流程图文档化
+- #10 看板刷新
+
+**暂缓(等用户/外部)**:
+- #108 Gitea push
+- #31 docker registry
+- #43 HTTPS 证书
+- #53 企微验证
+
+## Why
+v0.7.1 已 release,P0 全清;剩余都是 P1/P2,用户应有选择权决定下一版本范围。
+
+## How to apply
+下次用户问"接下来做什么"或"v0.7.2 规划",直接给这份清单让用户选。