simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5311a526af4e354aa125b82c216c5cafc3604049
wecom_it_smart_desk/docs/07-项目管理/项目全面评估报告-2026-06-25-archived-20260704.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

350 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 企微IT智能服务台 — 项目全面评估报告
> **评估日期**: 2026-06-25
> **评估范围**: 全量代码库（后端 178 个 .py 文件 + 4 个前端 + 部署配置 + 文档体系）
> **项目周期**: 2025-12 至今（约 7 个月）
> **当前版本**: v0.7.1
> **目标用户**: 公司 6000+ 员工
---
## 一、评估总览
| 评估维度 | 评分 | 说明 |
|---------|------|------|
| 架构设计 | ⚠️ 7/10 | 层次清晰，但单体瓶颈已显现 |
| 代码质量 | ⚠️ 6.5/10 | 后端良好，前端可优化空间大 |
| 测试覆盖 | ⚠️ 5/10 | 后端有测试但 64 条失败，前端零测试 |
| 安全性 | ⚠️ 6.5/10 | 多次 P0 修复，但仍有遗留风险 |
| 文档完整性 | ✅ 9/10 | 50+ 份文档，远超同类项目 |
| 部署运维 | ⚠️ 5.5/10 | 手动部署，单点风险，无 CI/CD |
| 项目管理 | ⚠️ 6/10 | 任务跟踪良好但用户是唯一瓶颈 |
| **综合健康度** | **🟡 6.5/10 — 可用但有风险** |
---
## 二、架构评估
### 2.1 优势
1. **清晰的层次分离** — API 层 / Service 层 / Model 层职责分明，28 个 router 文件 + 20 个 service 文件组织合理
2. **合理的抽象设计** — `ExternalSystemAdapter` 抽象层统一外部系统集成接口，支持降级和缓存
3. **WebSocket 双模式** — 实时推送 + 轮询降级，含指数退避重连
4. **统一响应格式** — `{code, data, message}` 统一错误码体系
5. **4 前端独立工程** — 坐席/H5/管理后台/Portal 各司其职
### 2.2 关键问题
| # | 问题 | 严重度 | 影响 |
|---|------|--------|------|
| A1 | **单体后端无拆分** — 20 个 service 全部在一个 Python 进程 | 🟠 中 | 不可独立扩缩，故障影响面大；`message_router.py` 671 行，`session_service.py` 1234 行已经过大 |
| A2 | **无消息队列** — 所有业务同步处理，未引入 RabbitMQ/Kafka/Redis Stream | 🟠 中 | AI 回复耗时会阻塞请求链路；高并发下后端的请求处理能力受限于最慢的同步操作 |
| A3 | **WebSocket 单点** — 一个 ws_manager 进程管理所有连接 | 🔴 高 | 容器重启导致所有连接断开，生产环境已有坑记录；无跨进程 WS 广播方案 |
| A4 | **AI 层未集成** — Dify/RAGFlow 仅基础占位，路由已就绪但未启用 | 🔴 高 | README 自述"AI 自助解决率 70.2%"，但当前新会话直接进人工队列 — 核心能力缺失 |
| A5 | **单数据库实例** — 无读写分离，无连接池监控 | 🟢 低 | 6000 用户并发访问压力下，单 PG 实例是潜在瓶颈 |
### 2.3 改进建议
1. **引入消息队列**：用 Redis Stream（已有 Redis 基础设施）解耦 AI 回复、消息路由等耗时操作
2. **WebSocket 水平扩展**：改用 Redis Pub/Sub 实现跨进程 WS 广播（ws_manager 框架化）
3. **后端模块化**：将 AI 处理、消息路由、外部系统集成拆分为独立微服务或异步 Worker
4. **AI 集成优先**：Dify 凭证已在 docker-compose 中预留，应优先补齐 AI 自动回复能力
---
## 三、代码质量评估
### 3.1 后端
- **28 个 API 文件**, **20 个 service 文件**, **18 个模型文件** — 组织合理
- 文件注解完备（每个 API 文件注释齐全），参数命名规范
- 部分文件过大：`admin_service.py` (1,728 行), `session_service.py` (1,234 行), `message_router.py` (671 行)
### 3.2 前端（4 端）
- 坐席工作台 `Workspace.vue` 复杂度高（三栏动态切换，多个 v-if/v-else-if）
- 前端类型定义与后端存在字段映射问题（已知 `MessageResponse.id` vs `message_id` 的 CRITICAL 映射）
- 缺少前端单元测试和组件测试
- 部分组件缺少 loading/error/empty 三态处理
### 3.3 依赖管理
- `requirements.txt` 版本锁定清晰，含完整注释说明每个依赖的作用
- 已知历史问题：`pydantic==2.7.5` 被 PyPI yank，需锁定 `2.7.4`
- **无前端依赖 lock 文件** — `package-lock.json` 或 `yarn.lock` 未归档
- **无依赖安全审计** — dependabot 配置了 `.gitea/dependabot.yml` 但 Gitea 是否支持不确定
### 3.4 改进建议
1. **大文件拆分**：`admin_service.py` 按模块拆分，`session_service.py` 按生命周期阶段拆分
2. **前端测试**：核心组件（ChatArea/ConversationList）引入 Vitest + Vue Test Utils
3. **前端依赖锁**：`npm run build` 前验证 package-lock.json 存在
4. **类型对齐**：后端 OpenAPI → 前端 TypeScript 代码生成（使用 openapi-typescript 工具）
---
## 四、测试评估
### 4.1 现状
| 测试类型 | 数据 | 状态 |
|---------|------|------|
| 后端 pytest 文件 | 25 个测试文件 | ✅ 存在 |
| 总测试用例 | ~538 条 | ⚠️ |
| 通过 | 470 passed + 4 xfailed | ✅ |
| 失败 | **64 条 pre-existing 失败** | 🔴 |
| 前端测试 | **0** | 🔴 完全缺失 |
| E2E 测试 | 176 行检查清单 | ✅ 文档化但未自动化 |
| 集成测试 | 62 tests collected，Windows 环境卡 conftest | ⚠️ 已知问题 |
### 4.2 关键问题
| # | 问题 | 严重度 |
|---|------|--------|
| T1 | **64 条测试持续失败** — 被标记为 pre-existing，无人修复 | 🔴 高 |
| T2 | **conftest SQLite+StaticPool 在 Windows 卡死** — 本地无法跑全量测试 | 🔴 高 |
| T3 | **前端零测试** — 4 个前端项目没有任何单元/组件/E2E 测试 | 🔴 高 |
| T4 | **无 CI 门禁** — 没有"测试通过才能合入"的流水线 | 🟠 中 |
| T5 | **Mock 依赖强耦合** — conftest 的 patch 路径耦合代码结构 | 🟠 中 |
### 4.3 改进建议
1. **根治 64 条失败** — 每个 sprint 分配 10% 时间专门修复，按模块优先级推进
2. **conftest 重写** — 用 `PostgreSQL testcontainers` 替代 SQLite，彻底解决兼容性问题
3. **前端测试筑基** — 从最核心的消息列表和发送组件开始，逐步扩展到 30% 覆盖率
4. **Git Hooks** — `pre-commit-check.sh` 已存在，但应加入"新增 API 端点必加 Depends"的静态检查
---
## 五、安全评估
### 5.1 已完成的安全工作（值得肯定）
- ✅ 5 个 P0 鉴权漏洞已修复
- ✅ WS token 改走 `Sec-WebSocket-Protocol`
- ✅ 坐席密码 bcrypt 迁移
- ✅ nginx access_log 脱敏
- ✅ MFA/TOTP 二次验证（Google Authenticator 兼容）
- ✅ 高危操作守卫（HighRiskGuard）
- ✅ CSP/HSTS/X-Frame-Options 等安全头
- ✅ 异常信息脱敏
### 5.2 遗留风险
| # | 风险项 | 状态 | 严重度 | 存在时间 |
|---|--------|------|--------|----------|
| S1 | **nginx IP 白名单开 0.0.0.0/0** — 临时方案，攻击面大 | ⚠️ 待处理 | 🔴 高 | 11 天 |
| S2 | **Token 未绑定 IP/设备** — 任何获取 token 者可冒用 | ⚠️ 待处理 | 🟠 高 | 11 天 |
| S3 | **未实现全端速率限制** — 仅登录端点有限制 | ⚠️ 待处理 | 🟠 中 | 11 天 |
| S4 | **Upload 路径在容器本地** — 容器重建后文件丢失 | ⚠️ 待处理 | 🟠 高 | 11 天 |
| S5 | **Gitea 无异地备份** — 仅 NAS 本地 | ⚠️ 待处理 | 🟠 中 | 11 天 |
| S6 | **Nginx client_max_body_size 未按路径细分** | ⚠️ 待处理 | 🟢 低 | 11 天 |
| S7 | **前端硬编码配置** — 配置未通过运行时注入 | ⚠️ 待处理 | 🟢 低 | 11 天 |
### 5.3 改进建议
1. **立即收窄 IP 白名单**：联系网络组确认 WAF/堡垒机/CDN 出口 IP，替换 0.0.0.0/0
2. **Token 绑定增强**：Redis 中存储 token 时绑定用户 IP 段（可选 /24）或浏览器指纹
3. **全端速率限制**：用 slowapi 为所有 API 端点分级限流（登录 10/min，通用 60/min，管理 30/min）
4. **Upload 持久化**：加 docker volume mount 解决重建丢文件问题
5. **Gitea 异地备份**：备份到 NAS 另一存储池 + 定期下载到本地（或公司备份系统）
---
## 六、部署与运维评估
### 6.1 现状
| 维度 | 当前状态 | 目标状态 |
|------|---------|---------|
| 编排方式 | Docker Compose 单机 | K8s 集群（规划中） |
| 部署方式 | 手动打包 → 堡垒机上传 → 解压部署 | CI/CD 自动化 |
| HTTPS | 已配置（443 + 301 跳转） | — |
| 健康检查 | 已配置但有 curl 已知坑 | 稳定可靠 |
| 容器镜像管理 | 本地构建，无 registry | Harbor/阿里云镜像仓库 |
| 数据库备份 | 无自动化备份 | cron 定期备份 |
| 日志管理 | docker logs + json-file driver | 集中式日志（ELK/Loki） |
| 监控 | /health 端点 + dashboard.py | Prometheus + Grafana |
### 6.2 关键问题
| # | 问题 | 严重度 |
|---|------|--------|
| D1 | **手动部署高风险** — 依赖堡垒机手动上传，无回滚按钮 | 🔴 高 |
| D2 | **无容器镜像 Registry** — 每台机器本地构建镜像，版本不可追溯 | 🟠 中 |
| D3 | **单点故障** — 后端/PG/Redis 全部在同一 Docker 主机 | 🔴 高 |
| D4 | **无自动化备份策略** — 数据库无定期 dump，Redis 仅 AOF | 🔴 高 |
| D5 | **Docker Compose env 密码明文风险** — .env 文件存密码 | 🟠 中 |
| D6 | **部署包打包工具 package.py 曾缺少 Portal 和 Admin** — 2026-06-15 已修复 | ✅ 已修 |
### 6.3 改进建议
1. **短期：加固部署流程**
- `scripts/deploy.sh` 增加回滚模式（保留前 3 个版本的部署包）
- 部署前自动备份数据库（`docker compose exec postgres pg_dump`）
- 部署后自动触发健康检查 + 5 分钟观察期
2. **中期：镜像管理与 CI/CD**
- 搭建 Harbor（NAS 上即可）作为私有镜像仓库
- GitHub Actions 或 Gitea Actions 实现自动构建 + push
- 服务器 pull 新镜像实现零停机部署
3. **长期：高可用架构**
- PostgreSQL 主从 + PgPool-II
- Redis Sentinel 集群
- 后端多副本 + Nginx 负载均衡
- 多 Docker 主机（Swarm/K8s）
---
## 七、文档与项目管理评估
### 7.1 文档优势
- ✅ 50+ 份文档覆盖架构/PRD/部署/审计/风险/SOP/ADR
- ✅ README 有分角色阅读指南（新人/开发/运维/测试）
- ✅ 风险跟踪表 22 项（含处理计划和责任人）
- ✅ CHANGELOG 严格按 Keep a Changelog 格式
- ✅ CURRENT-FOCUS.md 作为驾驶舱仪表盘
- ✅ 知识库 KNOWLEDGE.md 23 章 1000+ 行
### 7.2 问题
| # | 问题 | 严重度 |
|---|------|--------|
| P1 | **工作记忆文件过大被截断** — `MEMORY.md` 超过 3000 字符限制 | 🔴 高 |
| P2 | **风险跟踪表 11 天未更新**（上次 2026-06-14） | 🟠 中 |
| P3 | **用户是唯一决策者** — 所有 P2 任务标的"等用户决策"，无自主推进机制 | 🟠 中 |
| P4 | **CURRENT-FOCUS.md 状态混乱** — 同时存在多个不同时间的 P2 等决策表 | 🟠 中 |
| P5 | **无 Sprint 回顾记录** — 无经验教训的结构化沉淀 | 🟢 低 |
### 7.3 改进建议
1. **立即整理 MEMORY.md**：合并重复项，删除过期记录，控制在 3000 字符内
2. **风险跟踪表定期更新**：每周一自动检查，标注处理进度
3. **设立"自动推进"机制**：对重复出现的 P2 项（如镜像仓库、HTTPS），设定 next-review-date 到期自动提醒
4. **文档审计周期**：每两周审查一次关键文档（风险跟踪表 + CURRENT-FOCUS.md）
---
## 八、风险汇总矩阵
| 级别 | 基础架构 | 安全 | 功能交付 | 运维 | 项目管理 |
|------|---------|------|---------|------|---------|
| 🔴 高 | WS 单点 / 单体后端瓶颈 | IP 白名单全开 / Token 无绑定 | AI 集成未完成 | 无备份 / 手动部署高风险 | MEMORY.md 截断 |
| 🟠 中 | 无消息队列 / 单 DB | 速率限制不全 / Upload 丢文件 | 外部系统集成不全(aTrust/eHR) | 无镜像 Registry / 单点故障 | 用户单一瓶颈 / 风险表过期 |
| 🟢 低 | 前端组件未拆分 | 前端硬编码 / Nginx 文件限制 | 满意度评价未开始 | .env 明文密码 | 无 Sprint 回顾 |
### 当前风险热力图
```
高危区（P0，须即刻处理）：
┌─────────────────────────────────────────────┐
│ ■ AI 集成未完成（核心功能缺失） │
│ ■ nginx IP 白名单 0.0.0.0/0（攻击面大） │
│ ■ MEMORY.md 截断（项目记忆丢失风险） │
│ ■ 无自动化数据库备份（数据丢失即永远丢失） │
└─────────────────────────────────────────────┘
中危区（P1，2 周内处理）：
┌─────────────────────────────────────────────┐
│ ■ 64 条测试失败（质量信号失真） │
│ ■ 前端零测试（回归风险不可控） │
│ ■ 上传文件容器重建丢失（数据不持久） │
│ ■ 单体后端超负荷（session_service 1234行） │
└─────────────────────────────────────────────┘
低危区（P2，纳入 Sprint）：
┌─────────────────────────────────────────────┐
│ ■ WebSocket 单点（断连重建体验差） │
│ ■ 无镜像 Registry（版本不可追溯） │
│ ■ 风险跟踪表过期（11 天未更新） │
│ ■ 用户单一决策瓶颈（P2 任务堆积） │
└─────────────────────────────────────────────┘
```
---
## 九、推进计划
### 9.1 Phase 1 — 立即止血（1-3 天）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P0 | **收窄 nginx IP 白名单** — 联系网络组获取 WAF/CDN 出口 IP | S1 | 1 天（等回复） |
| P0 | **清理 MEMORY.md** — 合并去重，控制 3000 字符 | P1 | 1 小时 |
| P0 | **配置数据库自动备份** — 写入 cron，每天凌晨全量 dump | D4 | 2 小时 |
| P1 | **Upload 加 volume mount** — 解决容器重建丢文件 | S4, D6 | 30 分钟 |
| P1 | **修复 conftest SQLite+StaticPool** — 让本地测试可用 | T2 | 2 小时 |
### 9.2 Phase 2 — 核心功能补齐（1-2 周）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P0 | **AI 集成** — Dify 接入（凭证已有，路由就绪，缺工作流对接） | A4 | 3-5 天 |
| P1 | **修复 64 条测试** — 按模块逐个排查修复 | T1 | 3 天 |
| P1 | **前端测试筑基** — ChatArea/ConversationList 核心组件测试 | T3 | 2 天 |
| P1 | **全端速率限制** — slowapi 覆盖所有 API 端点 | S3 | 1 天 |
| P2 | **Token 绑定 IP** — Redis 存储时绑定客户端 IP | S2 | 1 天 |
### 9.3 Phase 3 — 基础设施加固（2-4 周）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P1 | **搭建私有镜像 Registry**（NAS Harbor） | D2 | 2 天 |
| P1 | **Gitea Actions CI/CD** — 自动构建 + push + 部署 | D1, T4 | 3 天 |
| P1 | **大文件服务拆分** — admin_service / session_service 按模块拆分 | A1 | 2 天 |
| P2 | **WebSocket 改用 Redis Pub/Sub** — 支持多进程广播 | A3 | 3 天 |
| P2 | **消息队列引入（Redis Stream）** — AI 回复异步化 | A2 | 3 天 |
### 9.4 Phase 4 — 架构演进（1-2 月）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P1 | **PostgreSQL 主从** — 配置流复制 | A5 | 3 天 |
| P2 | **前端组件全面重构** — 按功能模块拆分"巨石组件" | — | 1 周 |
| P2 | **E2E 自动化** — Playwright/Cypress 端到端测试 | — | 1 周 |
| P3 | **外部系统集成补齐** — aTrust + eHR 对接 | — | 1 周/系统 |
| P3 | **K8s 迁移评估** — 可行性分析 + 资源估算 | — | 3 天 |
### 9.5 时间线总览
```
Week 1 Week 2 Week 3-4 Month 2
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐
│ Phase 1 │ → │ Phase 2 │ → │ Phase 3 │ → │ Phase 4 │
│ 止血 │ │ 补功能 │ │ 加固 │ │ 演进 │
├─────────┤ ├─────────┤ ├──────────┤ ├──────────────┤
│ IP白名单│ │ AI集成 │ │ 镜像Registry│ │ PG主从 │
│ MEMORY │ │ 修测试 │ │ CI/CD │ │ 前端重构 │
│ 数据库备份 │ │ 前端测试 │ │ 服务拆分 │ │ E2E自动化 │
│ Upload修复│ │ 限流 │ │ WS优化 │ │ 外部系统补齐 │
│ conftest│ │ Token绑定│ │ 消息队列 │ │ K8s评估 │
└─────────┘ └─────────┘ └──────────┘ └──────────────┘
```
---
## 十、总结
### 10.1 值得肯定的成就
- **7 个月从零到 v0.7.1**，4 个前端 + 完整后端，产品功能全面
- **安全意识高** — 多次 P0 安全修复，已实施 MFA、高危守卫、安全头等
- **文档体系远超同类项目** — 50+ 份文档，ADR、SOP、风险跟踪表一应俱全
- **工程规范良好** — CHANGELOG 标准格式、提交约定、分支模型
### 10.2 最需要关注的 3 件事
1. **🔴 AI 集成** — 这是项目的核心价值主张，"AI 驱动"写在项目名称里，不能只有人肉坐席
2. **🔴 测试体系** — 64 条失败 + 前端零测试，质量门禁缺失，这是长期积累的债务
3. **🔴 部署与运维** — 无自动化备份、手动部署、单点故障，一旦出问题恢复时间不可控
### 10.3 一句话评估
> **项目功能完整、文档优秀、安全根基扎实，但核心 AI 能力缺失和测试体系薄弱是当前最大的风险敞口。建议在推进新功能前，集中 1-2 周补齐这两块短板。**
---
*报告由 软件开发团队·主理人 齐活林 编制 | 2026-06-25*
Reference in New Issue View Git Blame Copy Permalink