# ChatOA 开发进度存档

> 本文件用于在更换环境 / 重新安装 CodeBuddy / 更换文件夹路径后，快速恢复开发上下文、省积分启动项目。
> 最后更新：2026-08-23 ｜ 当前版本：v0.1.0 ｜ 已提交并推送（远程 `ChatOA`）

## 一、项目速览

- **定位**：一站式 IM + OA 办公桌面客户端（类似微信电脑端），集成聊天、联系人、日程、表单、笔记、应用、网盘、AI 助手。
- **技术栈**：
  - 客户端：Electron + Vite + React 18 + TypeScript + Ant Design 5 + Zustand + Socket.IO client
  - 服务端：NestJS 11 + TypeScript + JWT + Socket.IO + JSON 文件持久化（预留 Mongo/Redis）
- **目录结构**：
  ```
  ChatOA/
  ├── server/            # NestJS 服务端（端口 3000，路由前缀 /api）
  ├── client/            # Electron + Vite 客户端（dev 端口 5173）
  │   ├── electron/      # Electron 主进程（main.cjs, preload.cjs）
  │   ├── src/
  │   │   ├── pages/     # 8 个页面 + Login + Placeholder
  │   │   ├── layout/    # MainLayout（左侧图标导航 + KeepAliveOutlet）
  │   │   ├── components/ # ChatWindow, ConversationList, ProfileModal
  │   │   ├── store/     # Zustand: auth.ts, chat.ts
  │   │   ├── api/ socket/ constants/ utils/
  │   └── release/       # 打包产物（.exe）
  ├── screenshots/       # 界面截图 + ChatOA推文.md
  ├── 项目要求.md        # 需求基线 + 完成状态
  └── 开发进度存档.md    # 本文件
  ```

## 二、快速启动（新环境首次）

```powershell
# 1) 安装依赖
cd server; npm install
cd ..\client; npm install

# 2) 启动服务端（nodemon 热重载，端口 3000，自动 seed 演示数据）
cd server; npm run start:dev
# 验证: 浏览器打开 http://localhost:3000/api/... 或看控制台 "[ChatOA] server running at http://localhost:3000"

# 3) 启动客户端（Vite + Electron 桌面窗口）
cd client; npm run dev

# 4) 仅浏览器调试（最快，不带 Electron）
cd client; npm run dev:web

# 5) 打包便携版 exe
cd client; npm run build:portable   # 产物 client/release/ChatOA-Portable-0.1.0-x64.exe
```

**演示账号**：`demo / 123456`（另含 alice 小艾、bob 小波、carol 小卡，密码均 123456）

**重要运行前提**：打包版 exe 是 `file://` 协议直连 `http://localhost:3000/api`，运行 exe 前必须先启动服务端。

## 三、完成功能清单（截至 v0.1.0）

| 模块 | 状态 | 说明 |
|------|------|------|
| 登录/认证 | ✅ | JWT 7 天；有演示账号一键登录按钮 |
| 聊天 | ✅ | 会话列表+窗口、置顶、搜索、图片/文件/单据/日程/云盘/笔记/表情/截图插入、商务化卡片（表单卡片可点开审批） |
| 联系人 | ✅ | 同事/AI助手/朋友三组、添加好友、在线人数徽章 |
| 日程 | ✅ | 左小月历+事件点标记（日程/生日/纪念日）+今日/明日/一周 Tab，右大月历 |
| 表单 | ✅ | 5 种模板（请假/会议室/场地借用/公车/报销）、模板库+我的实例、审批状态（localStorage 持久化） |
| 笔记（知识库） | ✅ | 多级目录+搜索、目录后笔记条数、多页签、HTML 富文本编辑、自动保存 |
| 应用 | ✅ | 我的应用/应用市场双 Tab、搜索、极简日历应用（market-calendar-lite）、分组折叠 |
| 网盘 | ✅ Demo | 本机/我的/团队/系统/分享/回收站、面包屑、上传/删除/还原、容量条 |
| AI 助手 | ✅ Demo | 独立主导航入口、多模型切换（GPT-4o/Claude 3.5/DeepSeek/通义千问/豆包）、纯前端模拟 |
| 个人资料弹窗 | ✅ | 左下角头像→修改签名、设置状态（上班/外出/出差/请假/学习/休假） |
| 标题栏版本号 | ✅ | `ChatOA v0.1.0`，版本唯一来源 `client/package.json` |

## 四、关键架构约定（改代码前必读）

1. **KeepAlive 路由铁律**：`App.tsx` 中 `/ai-chat` 与 `/ai-chat/:assistantId` 必须都渲染 `KeepAliveOutlet`（相同类型组件）。若改用 `<Navigate>` 会卸载 Outlet，导致所有 keep-alive 页面状态（如应用页打开的运行页签）在切走切回时被重置。新增页面请照此模式加入 `<Route path="/xxx" element={<KeepAliveOutlet />} />`。
2. **版本号**：只改 `client/package.json` 的 `version`，Vite `define` 注入 `__APP_VERSION__`，`main.tsx` 设 `document.title`，`electron/main.cjs` 用 `app.getVersion()`。
3. **存储**：服务端 `server/src/config.ts` 控制存储类型（默认 `json`，JSON 文件持久化）；`seed.service.ts` 每次启动自动灌演示数据。
4. **应用市场注册**：外部应用在 `EXTERNAL_PROJECTS` 中配置，其 key 必须与市场应用 id（如 `market-calendar-lite`）一致，否则「使用」和「关联项目」匹配不上。
5. **路由策略**：浏览器开发用 `BrowserRouter`，Electron 打包后 `file://` 自动切 `HashRouter`（`App.tsx` 内判断）。
6. **统一宽度**：1-7 个模块的第二列（列表区）宽度全局统一。

## 五、已知注意事项（踩坑记录）

- **PowerShell 中文路径乱码**：绝对路径含「范先生」会乱码，务必用相对路径 `cd server` / `cd client` 再执行命令；git 提交信息乱码只是显示问题，存储正常。
- **git 远程名**：远程叫 `ChatOA` 而非 `origin`，推送用 `git push ChatOA main`；main 未设上游，可先 `git push -u ChatOA main` 绑定。
- **打包版与调试版一致性**：重新打包前确保 `npm run build`（Vite 产物）最新，避免 exe 里是旧代码。
- **临时验证产物**：根目录的 `*.png`（调试截图）与 `forms*.yaml`（UI 快照）已加入 `.gitignore`，勿提交。
- **JWT 密钥**：`server/src/config.ts` 默认 `chatoa-dev-secret-change-me`，生产需用环境变量 `JWT_SECRET`。

## 六、git 状态（2026-08-23）

- 最新提交：`66f10705 feat: 标题栏版本号 + 应用市场上架日历应用与分组折叠 + 日程农历/表单横版优化 + 个人资料弹窗`（22 files, +545/-29）
- 已推送至远程 `ChatOA`：`62776aa3..66f10705 main -> main`
- 远端：`https://github.bbitcn.net/fanhongcai/ChatOA.git`（本地 remote 名 `ChatOA`）

## 七、Roadmap

- 接入真实大模型 API
- 表单审批链路后端化
- 网盘 OSS / 文件同步
- 消息已读回执、撤回、引用
- MongoDB / Redis 生产存储
- 移动端适配