# 企微IT智能服务台 — 项目状态看板

> 📌 **这个文件就是项目的"驾驶舱仪表盘"**。任何时候新开 session,**先读这个文件就懂上下文**。
>
> 📝 **更新规则**:每次 Claude 完成 / 开始 / 阻塞重要任务,会主动更新本文件。你也可以自己改(纯 markdown,git 跟踪)。

最后更新:**2026-06-16 11:10**(Claude 自动维护,看板上一次刷新)

---

## 🎯 一句话总览

**项目状态**:**v0.5.6-dev-tooling 完成**,本地 4 端 dev 链路全通(Mock 企微 OAuth + 3 个新 migration + 1 个 decorator bug 修复)。
**当前主线**:**等用户决策要不要上生产**(生产 3 个 migration + 1 个 bug 修复可上,7 个 dev 改动留在本地)。
**待回复**:#83 OTM 是什么 / 跟项目什么关系。

---

## 🟢 正在做(in_progress,1 件)

| # | 任务 | 我做什么 | 你做什么 | 完成定义 |
|---|---|---|---|---|
| #90 | 后端 pytest 测试套件 | 补 token_service / scoring_service 等 | 等结果 | 20+ 测试通过 |

---

## 🔴 P0 必做(下一个 sprint)

| # | 任务 | 重要程度 | 说明 |
|---|---|---|---|
| #48 | v1.0 收窄 set_real_ip_from | 🔴 P0 | 现 allow 0.0.0.0/0 是临时方案,正式上线前必须改精确代理 IP |
| #81 | v0.6.0 敏感词检测 + 语气优化 | 🔴 P0 | 下一个版本的核心功能 |
| #80 | v0.5.4 应急页 nginx 路由 + 部署 | 🔴 P0 | 当前生产缺路由,功能上了但用户访问不到 |

---

## 🟡 P1 重要(看时间做)

| # | 任务 | 说明 |
|---|---|---|
| #73 | 修后端文件未真正覆盖 | `yes | cp -f` 路径,部署时偶尔没生效 |
| #86 | 排查流程图零依赖部分 review + 文档化 | 把 Mermaid 流程图从代码里剥离成可读文档 |
| #88 | 管理后台 RBAC 角色权限 | 管理后台细粒度角色权限(大功能,2-3 天) |
| #83 | 澄清"OTM 跟项目关系" | **我在这等你回答**:OTM 是什么?需要对接吗? |

---

## 🟢 P2 / 等用户决策

| # | 任务 | 卡在哪 |
|---|---|---|
| **🆕 服务器更新?** | 把今天的 3 个 migration + 1 个 bug 修复部署到生产 v0.5.6 | **等你看这份看板后拍板** |
| #31 | 推 docker 镜像到生产 registry | 等你确认要走哪条路(自建 Harbor / 阿里云 / 别的) |
| #43 | 配置 HTTPS | 等域名备案完成 + 证书到位 |
| #53 | 用户在企微验证 /itportal/ | 等你去企微点一点 |

---

## ✅ 最近搞定(给你信心)

### 2026-06-16(今天)

#### 🛠️ Dev 环境(本地链路全通)

- ✅ **本地 dev 4 端链路跑通**(#89-92):
  - backend (8000) + h5 (5174) + agent (5173) + admin (5175) + portal (5176) 全起
  - Mock 企微 OAuth 全通(`/api/dev/login` 给 token)
  - portal → H5 / 坐席 / 管理员 跳转正常
- ✅ **修了 3 个 dev 启动坑**:
  1. `pydantic==2.7.5` → `2.7.4`(2.7.5 被 PyPI yank)
  2. docker-compose 加 `PYTHONPATH=/app`(alembic 1.13+ 不再默认 prepend cwd)
  3. dev 启动必须用 `--env-file .env.dev`(根 `.env` 冲突)

#### 🐛 Bug 修复

- ✅ **#93 修 portal dev 模式跳错端口**:`import.meta.env.DEV` 判断,生产走相对路径,dev 走完整 URL
- ✅ **#97 修 require_role 装饰器**:`@wraps` 让 FastAPI 看到 `__wrapped__` 签名,Depends 未被解析 → `current_user` 实际是 Depends 对象。用 `inspect` 合并 signature + 手动设 `wrapper.__signature__` 修
- ✅ **#99 dev 模式短路企微推送**:避免 `.env.dev` 用 `dev_corp_id_xxxxx` 调企微 API 返 `invalid corpid` 噪音

#### 🗃️ 数据库 migration(3 个)

- ✅ **#94 alembic 010**:加 `agents.otp_secret` + `agents.otp_enabled`
- ✅ **#94 alembic 011**:加 `conversations.impact_scope` + `is_blocking` + `emotion_state`(用户坐席发消息 500 的真因)
- ✅ **#96 alembic 012**:加 `conversations.dify_conversation_id` + `employees.it_level` + `it_level_source` + `notes`

#### 🛡️ 防错工具(留底用)

- ✅ **#95 dev-check-schema-drift.ps1**:对比 SQLAlchemy 模型 vs Postgres schema,漂移 exit 1。以后模型加字段忘 migration 一跑就发现(用 docker exec,免去 Python 依赖)

#### 📋 其他

- ✅ **#68 H5 空白页闪一下**:dev 模式验证不再白屏(生产未复测)

### 历史(选重点)

- ✅ v0.5.5:应急页 v0.5.4 + 移除 IT 设备升级 + admin 登录修复 + 内容审核架构
- ✅ v0.5.3:重打后端部署包(5 IT + 2 HR + 1 行政 + 1 财务 = 9 条)
- ✅ v0.5.6-dev-tooling 已 tag + push gitea(本地 dev 工具集)
- ✅ messages.id varchar=UUID SQL bug 修了(#60)+ 10 个回归测试通过
- ✅ nginx /api/admin/ 和 /itadmin/ 修复 403/allow(#57)

---

## 🚀 怎么跑起来(3 步)

### 1. 后端 dev(已经在跑 ✅)

```powershell
cd D:\资料\03-项目开发\wecom_it_smart_desk-claude
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d
curl http://localhost:8000/api/dev/health
```

### 2. 前端 dev(已经在跑 ✅)

```powershell
# 一次性装 4 个前端依赖(已装好)
.\scripts\dev-frontend-install.ps1

# 之后:一起起所有前端
.\scripts\dev-frontend-start.ps1
# 单独停:.\scripts\dev-frontend-start.ps1 -Stop
```

### 3. 浏览器验证

- portal:http://localhost:5176/itportal/select
- H5:http://localhost:5174/itdesk/
- 坐席:http://localhost:5173/itagent/
- 管理员:http://localhost:5175/itadmin/

---

## 📌 怎么读这份文档

**你是运维小白,不需要懂代码**。看这个文件就能 1 分钟懂:

1. **"现在在干嘛?"** → 看「正在做」表
2. **"接下来要干嘛?"** → 看「P0 必做」表
3. **"我需要做什么?"** → 看「正在做」表里的「你做什么」列
4. **"今天有啥进展?"** → 看「最近搞定」

---

## 🤖 Claude 怎么帮你

每次开新 session 我会:

1. **第一件事**:读这个文件 + TaskList,告诉你"上次到这了"
2. **完成一件重要事**:更新这个文件(改状态、加完成项)
3. **遇到阻塞**:写在「P2 / 等用户决策」里,等你回话
4. **新需求进来**:跟当前 in_progress 比较,看是**接着做**还是**并行加**(参考你的"并行处理"反馈)

---

**这个文件就是你和 Claude 之间的"工作交接本"。有问题改这里就行。**