docs: requirements status tracking, dev progress archive and quick-start guide
This commit is contained in:
@@ -49,6 +49,11 @@ ChatOA/
|
||||
└── store/ # Zustand 状态
|
||||
```
|
||||
|
||||
## 开发文档
|
||||
|
||||
- `项目要求.md` —— 需求基线 + 每条完成状态
|
||||
- `开发进度存档.md` —— **新环境接手必读**：快速启动、功能清单、架构约定、踩坑记录、git 状态
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 启动服务端
|
||||
|
||||
@@ -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`（相同类型组件）。若改用 `<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 生产存储
|
||||
- 移动端适配
|
||||
@@ -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` 第二节。
|
||||
|
||||
Reference in New Issue
Block a user