From 972bbe724588b1853165326ca82e49db472909b9 Mon Sep 17 00:00:00 2001 From: fanhongcai Date: Sun, 23 Aug 2026 11:06:59 +0800 Subject: [PATCH] docs: requirements status tracking, dev progress archive and quick-start guide --- README.md | 5 ++ 开发进度存档.md | 101 +++++++++++++++++++++++++++++++++++++ 项目要求.md | 130 ++++++++++++++++++++++++++++++++++++------------ 3 files changed, 204 insertions(+), 32 deletions(-) create mode 100644 开发进度存档.md diff --git a/README.md b/README.md index 470b568..196b166 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,11 @@ ChatOA/ └── store/ # Zustand 状态 ``` +## 开发文档 + +- `项目要求.md` —— 需求基线 + 每条完成状态 +- `开发进度存档.md` —— **新环境接手必读**：快速启动、功能清单、架构约定、踩坑记录、git 状态 + ## 快速开始 ### 1. 启动服务端 diff --git a/开发进度存档.md b/开发进度存档.md new file mode 100644 index 0000000..b4555a2 --- /dev/null +++ b/开发进度存档.md @@ -0,0 +1,101 @@ +# 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`（相同类型组件）。若改用 `` 会卸载 Outlet，导致所有 keep-alive 页面状态（如应用页打开的运行页签）在切走切回时被重置。新增页面请照此模式加入 `} />`。 +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 生产存储 +- 移动端适配 diff --git a/项目要求.md b/项目要求.md index e96a76c..450340e 100644 --- a/项目要求.md +++ b/项目要求.md @@ -1,43 +1,109 @@ -这是一个 基于IM的OA客户端工具，项目名称叫ChatOA，通过即时通讯的方式实现对话、文件互传，表单签批等，用户为办公室人员，与微信电脑端类似，功能包含 1即时通讯对话 2联系人 3日程 4表单 5笔记 6应用 7网盘 -功能不需要一次性完成，单1 2 3 优先 ,5和4先做Demo 6 7属于扩展。 -整体结构参考微信电脑端，分三列，第一列为功能图标导航按钮 第二列为功能区：例如联系人列表等，第三列为主要工作区。 +# ChatOA 项目要求与完成状态 -技术路线： -**客户端**：Electron + React/Vue + TypeScript -**服务端**：Node.js + TypeScript（NestJS 或 Express） -**数据库**：MongoDB + Redis -**通信**：Socket.IO（WebSocket 封装） +> 本文档为 ChatOA 客户端的需求基线。原需求逐条保留，每条后标注当前完成状态。 +> 更新日期：2026-08-23 ｜ 当前版本：v0.1.0 -前端： -- 支持 Windows -- 包含登录页、聊天列表页、聊天窗口页的路由 -- 联系人页 -- 日程页 -- 表单页（自定义表单，支持创建、管理、填写，表单存储为Json格式） -- 集成 Socket.IO 客户端 +## 一、项目概述 -服务端： -用 Node.js + NestJS + TypeScript 写 IM 服务端， -模块包括： -- 用户认证（JWT） -- WebSocket 网关（Socket.IO） -- 消息存储（MongoDB） -- 在线状态管理（Redis） -- 离线消息推送 +这是一个基于 IM 的 OA 客户端工具，项目名称叫 ChatOA，通过即时通讯的方式实现对话、文件互传、表单签批等，用户为办公室人员，与微信电脑端类似。 -如果还有问题，请及时提出。 +功能优先级：1 即时通讯对话、2 联系人、3 日程 优先完成；5 笔记、4 表单先做 Demo；6 应用、7 网盘属于扩展。 +- [x] 整体结构参考微信电脑端，分三列：第一列为功能图标导航按钮，第二列为功能区（如联系人列表），第三列为主要工作区 —— **✅ 已完成** +## 二、技术路线 -知识库的设计逻辑为：笔记，分左右结构，左边为多级目录，支持搜索，左侧区域的宽度等于聊天界面对话列表区域的宽度（1-7个模块，需要全局统一宽度），右侧为笔记编辑界面。 +- [x] **客户端**：Electron + React + TypeScript —— **✅ 已完成**（Electron + Vite + React 18 + TS + Ant Design 5 + Zustand） +- [x] **服务端**：Node.js + TypeScript（NestJS）—— **✅ 已完成**（NestJS 11 + Socket.IO + JWT） +- [ ] **数据库**：MongoDB + Redis —— **⏳ 预留**（当前 JSON 文件持久化，`server/src/config.ts` 已留 Mongo/Redis 配置位） +- [x] **通信**：Socket.IO（WebSocket 封装）—— **✅ 已完成** -应用页面：分左右结构，左边为两个Tab，一个为我的应用，另一个为应用市场，支持搜索，右侧为应用的展示、操作区，模拟几个应用。 -网盘页面：先做Demo，分左右结构，左边为 搜索结果，本机文件，我的文件，团队文件，系统文件，分享文件，回收站 几个导航菜单，底部显示云盘的容量和使用情况。右侧为文件夹显示区域。 -日程页面：分左右结果，左侧区域上面一个小型月历视图，用点标记日程、生日、纪念日等，左侧下方显示 分多个tab页：今日（默认）、明日、一周内等信息。右侧为大型月历视图。 +## 三、前端要求 -知识库（笔记）页面调整项：1图标和文字需要保持在同一行。2左边文件夹目录后面显示笔记条数。3右侧编辑区需要支持多页签。4笔记编辑组件采用html富文本编辑器。 +- [x] 支持 Windows —— **✅ 已完成**（Electron 便携版） +- [x] 包含登录页、聊天列表页、聊天窗口页的路由 —— **✅ 已完成** +- [x] 联系人页 —— **✅ 已完成** +- [x] 日程页 —— **✅ 已完成** +- [x] 表单页（自定义表单，支持创建、管理、填写，表单存储为 JSON 格式）—— **✅ 已完成** +- [x] 集成 Socket.IO 客户端 —— **✅ 已完成** -联系人页面：新增分组：同事（组织内好友）|AI助手（AI助手工具：单击后进入AI对话聊天界面，模型支持多种模型可选）|朋友（指非组织内朋友，通过添加好友的） 。 +## 四、服务端要求 -系统框架： -首页左下角个人头像图标，单击后 进行显示个人信息并修改签名、设置状态（内置 上班、外出、出差、请假、学习、休假等状态） +- [x] 用户认证（JWT）—— **✅ 已完成**（`server/src/auth`，JWT 7 天有效） +- [x] WebSocket 网关（Socket.IO）—— **✅ 已完成**（`server/src/chat`） +- [ ] 消息存储（MongoDB）—— **⏳ 预留**（当前 JSON 存储） +- [ ] 在线状态管理（Redis）—— **⏳ 预留**（当前 `presence` 模块 JSON 模拟） +- [ ] 离线消息推送 —— **⏳ 预留** + +## 五、各模块细化需求与状态 + +### 5.1 知识库（笔记） +- [x] 分左右结构，左边为多级目录，支持搜索，左侧区域宽度与聊天对话列表区域一致（1-7 个模块全局统一宽度）—— **✅ 已完成** +- [x] 右侧为笔记编辑界面 —— **✅ 已完成** +- [x] 图标和文字保持在同一行 —— **✅ 已完成** +- [x] 左边文件夹目录后面显示笔记条数 —— **✅ 已完成** +- [x] 右侧编辑区支持多页签 —— **✅ 已完成**（KeepAlive 多页签） +- [x] 笔记编辑组件采用 HTML 富文本编辑器 —— **✅ 已完成** + +### 5.2 应用页面 +- [x] 分左右结构，左边为两个 Tab：「我的应用」与「应用市场」，支持搜索 —— **✅ 已完成** +- [x] 右侧为应用的展示、操作区，模拟几个应用 —— **✅ 已完成** +- [x] 应用市场上架了「极简日历」应用（参考 calendarlite.bbitcn.net 产品）—— **✅ 已完成**（2026-08-21 新增） +- [x] 应用分组折叠 —— **✅ 已完成**（2026-08-22 新增） + +### 5.3 网盘页面 +- [x] 先做 Demo，分左右结构：左边为 搜索结果、本机文件、我的文件、团队文件、系统文件、分享文件、回收站 导航菜单，底部显示云盘容量与使用情况 —— **✅ 已完成** +- [x] 右侧为文件夹显示区域 —— **✅ 已完成** + +### 5.4 日程页面 +- [x] 分左右结构，左侧区域上面一个小型月历视图，用点标记日程、生日、纪念日等 —— **✅ 已完成** +- [x] 左侧下方分多个 Tab：今日（默认）、明日、一周内等 —— **✅ 已完成** +- [x] 右侧为大型月历视图 —— **✅ 已完成** + +### 5.5 联系人页面 +- [x] 新增分组：同事（组织内好友）| AI 助手（单击后进入 AI 对话界面，模型支持多种可选）| 朋友（非组织内朋友，通过添加好友）—— **✅ 已完成** + +### 5.6 系统框架 +- [x] 首页左下角个人头像图标，单击后显示个人信息并修改签名、设置状态（内置 上班、外出、出差、请假、学习、休假等状态）—— **✅ 已完成**（`client/src/components/ProfileModal.tsx`） + +## 六、迭代变更记录 + +| 日期 | 变更 | +|------|------| +| 2026-08-21 | 应用市场上架「极简日历」应用（market-calendar-lite），含功能预览卡片、EXTERNAL_PROJECTS 与市场应用 id 对齐 | +| 2026-08-22 | 应用分组折叠功能；顶部标题栏新增版本编号 `ChatOA v0.1.0`（版本号唯一来源 `client/package.json`，经 Vite define 注入 `__APP_VERSION__`） | +| 2026-08-23 | 首次提交并推送远程仓库；本文档更新为需求+完成状态双轨制；新增 `开发进度存档.md` | + +## 七、后续待办（Roadmap） + +- [ ] 接入真实大模型 API（OpenAI / Claude / 豆包等） +- [ ] 表单流程接入后端实例审批链路 +- [ ] 网盘接入 OSS / 本地文件同步 +- [ ] 消息已读回执、撤回、引用 +- [ ] 接入 MongoDB / Redis 生产级存储 +- [ ] 移动端响应式适配 + +## 八、快速启动（新环境省积分指南） + +> 更换文件夹路径 / 重新安装 CodeBuddy 后，按此快速恢复开发环境。完整细节见 `开发进度存档.md`。 + +```powershell +# 1. 安装依赖（首次） +cd server; npm install +cd ..\client; npm install + +# 2. 启动服务端（端口 3000） +cd server; npm run start:dev + +# 3. 启动客户端（Vite 5173，Electron 桌面窗口） +cd client; npm run dev + +# 4. 浏览器调试版（不带 Electron，最省资源） +cd client; npm run dev:web + +# 5. 打包便携版 exe +cd client; npm run build:portable +``` + +- 演示账号：`demo / 123456`（另含 alice / bob / carol，密码同 123456） +- 客户端启动方式详见 `开发进度存档.md` 第二节。