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    # 本文件

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

# 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`

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

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

6.3 KiB Raw Blame History Unescape Escape

ChatOA 开发进度存档

一、项目速览

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

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

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

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

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

七、Roadmap

6.3 KiB

Raw Blame History