From 6cd369f548debd47d36638d25af1aae6a75298da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BC=96=E7=A0=81=E5=B7=A5=E7=A8=8B=E5=B8=88?= Date: Sun, 23 Aug 2026 14:28:07 +0800 Subject: [PATCH] docs: add project handover handbook Co-authored-by: multica-agent --- docs/README.md | 26 +++++++++++++++++++++++ docs/employee-guide.md | 2 ++ docs/phase4-launch-checklist.md | 2 ++ docs/phase4-regression-2026-08-16.md | 2 ++ docs/任务清单.md | 26 +++++++++++++++++++++++ docs/最新进度.md | 31 ++++++++++++++++++++++++++++ docs/项目需求.md | 31 ++++++++++++++++++++++++++++ 7 files changed, 120 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/任务清单.md create mode 100644 docs/最新进度.md create mode 100644 docs/项目需求.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..605f3d0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# 畅联项目手册 + +这是项目的交接首页。新接手的人先按下面顺序阅读，不要只凭旧文档或聊天记录判断项目状态。 + +1. 先读 [项目需求](项目需求.md)：弄清楚项目要做什么、不能碰什么。 +2. 再读 [最新进度](最新进度.md)：确认代码已经做到哪里、哪些结论已经被验证。 +3. 最后读 [任务清单](任务清单.md)：从“正在做”和“还没安排”里选择下一件事。 + +## 仓库里有什么 + +- `mobile/`：手机端，使用 Flutter，含 Android 和 iPhone 的工程文件。 +- `pc-client/`：电脑端，使用 Electron，Windows 是当前优先支持的平台。 +- `account-service/`：公司账号服务，负责工号密码登录、管理员导入和管理名单。 +- `docker-compose.yaml`、`config/`、`scripts/`：OpenIM、语音服务和内网环境的配置及维护脚本。 +- `docs/`：本手册和以前留下的验收、回归、使用说明。 + +## 更新规矩 + +以后每完成、新增、取消或发现一个任务，负责这件事的智能体必须在同一次提交中顺手更新本目录： + +- 改需求或边界时，更新 `项目需求.md`。 +- 做完功能、修复问题、完成构建或验证时，更新 `最新进度.md`。 +- 任务状态变化时，更新 `任务清单.md` 的三栏，并写明依据。 +- 旧文档不能删除；如果它和当前事实不一致，在旧文档开头加“已过时，仅留档备查”提示，再在本目录写新版。 + +手册只记录已经确认的事实。拿不准的内容要写成“待确认”，不要当成已完成。 \ No newline at end of file diff --git a/docs/employee-guide.md b/docs/employee-guide.md index 68ca4f1..fbedd4c 100644 --- a/docs/employee-guide.md +++ b/docs/employee-guide.md @@ -1,3 +1,5 @@ +> ⚠️ 本文档已过时，仅留档备查，请勿删除。当前请先看 `docs/README.md`、`docs/项目需求.md`、`docs/最新进度.md` 和 `docs/任务清单.md`。 + # 畅联使用说明（一页纸） ## 这是什么 diff --git a/docs/phase4-launch-checklist.md b/docs/phase4-launch-checklist.md index b06ea0b..a9c8959 100644 --- a/docs/phase4-launch-checklist.md +++ b/docs/phase4-launch-checklist.md @@ -1,3 +1,5 @@ +> ⚠️ 本文档已过时，仅留档备查，请勿删除。当前请先看 `docs/README.md`、`docs/项目需求.md`、`docs/最新进度.md` 和 `docs/任务清单.md`。 + # 第4步 · 试用前部署与验收清单（B-61） > 本文件记录"50 人试用"前必须在服务器上手动完成的事项、验收清单与手机正式签名流程。 diff --git a/docs/phase4-regression-2026-08-16.md b/docs/phase4-regression-2026-08-16.md index 3c68f6d..7ad1d5e 100644 --- a/docs/phase4-regression-2026-08-16.md +++ b/docs/phase4-regression-2026-08-16.md @@ -1,3 +1,5 @@ +> ⚠️ 本文档已过时，仅留档备查，请勿删除。当前请先看 `docs/README.md`、`docs/项目需求.md`、`docs/最新进度.md` 和 `docs/任务清单.md`。 + # 阶段 4 跨端回归记录（2026-08-16） > 基线：`main` @ `a007e8f`（含 B-52 三项修复：发消息根因 `d6ef6eb`、同事页/五态 `b50ee24`+`c73e19c`、PC 通讯录入口 `032882d`，以及本轮版本号提升 `7eab7d5`、AUTH_HOST 联调开关 `a007e8f`）。 diff --git a/docs/任务清单.md b/docs/任务清单.md new file mode 100644 index 0000000..8d2a7ee --- /dev/null +++ b/docs/任务清单.md @@ -0,0 +1,26 @@ +# 任务清单 + +更新时间：2026-08-23。任务状态以当前仓库和项目约束为准；没有证据的事项不写成“已完成”。 + +## 正在做 + +目前没有已确认正在施工的业务代码任务。 + +本次已完成仓库交接手册整理，后续所有任务都应按 `docs/README.md` 的更新规矩同步维护本清单。 + +## 已做完 + +- 建立手机端 Flutter 工程和 Windows 优先的 Electron 电脑端工程。 +- 接入公司工号加密码登录，以及管理员导入、管理员工账号的账号服务。 +- 完成聊天、通讯录、同事申请、语音消息、文件/图片消息和一对一语音通话的相关代码接入。 +- 完成一轮手机与电脑的跨端回归记录；其中已通过的项目见旧档 `phase4-regression-2026-08-16.md`。 +- 将 LiveKit 的信令/媒体端口统一为 `17880`、`17881`、`17882`，并提供可重复执行的修复脚本。 +- 建立本目录四份交接手册，并为三份过时旧说明加上明确的留档提示。 + +## 还没安排 + +- 组织真实手机和 Windows 电脑的回归：重点确认文件传输和一对一语音通话。 +- 明确手机正式签名的负责人和安全保管方式；不能把签名密钥提交进仓库。 +- 获得负责人同意后，再导入真实员工名单并验证账号管理流程。 +- 等负责人对三个公网问题拍板后，才安排公网 IP/域名、备案、反向代理和 HTTPS 的具体施工；当前禁止擅自开始。 +- 公网方案获批后，重新评估电脑端 Electron、登录失败限制、令牌本地保存和跨域设置的安全风险。 \ No newline at end of file diff --git a/docs/最新进度.md b/docs/最新进度.md new file mode 100644 index 0000000..0848a72 --- /dev/null +++ b/docs/最新进度.md @@ -0,0 +1,31 @@ +# 最新进度 + +更新时间：2026-08-23。以下内容依据当前仓库代码和最新提交 `fa8584a` 整理。 + +## 现在做到哪里 + +项目已经具备可继续测试的手机端、Windows 电脑端、账号服务和内网部署配置： + +- 手机端在 `mobile/`，使用 OpenIM Flutter SDK `3.8.3+hotfix.12`，版本 `1.0.6+7`。 +- 电脑端在 `pc-client/`，使用 Electron，显示版本 `v1.0.2`。 +- 员工用工号和密码通过 `account-service/` 登录；管理员导入和管理账号的页面、接口已在仓库中。 +- 手机和电脑端已接入聊天、通讯录、同事申请、语音消息、文件/图片消息和一对一语音通话相关代码。 +- 语音服务 LiveKit 的信令和媒体端口已统一为 `17880`、`17881`、`17882`；仓库提供 `scripts/fix-livekit-ports.sh` 用于服务器已部署环境的端口修复。 + +## 已有验证记录 + +- `docs/phase4-regression-2026-08-16.md` 记录过手机与电脑之间的文字、同事申请、图片、语音消息等跨端回归结果。 +- 该记录中的文件传输和一对一语音通话，曾因模拟器环境无法闭环，仍需要用真实设备再次确认。 +- 旧记录使用的是更早的提交、安装包版本和端口状态；因此已保留为档案并在开头标明过时，不能当作当前验收结论。 + +## 当前停在哪 + +公网接入施工暂停，等待负责人对三个公网相关问题拍板后再恢复。现阶段没有把内网服务发布到公网的授权。 + +这意味着：代码可继续维护和内网验证，但公网 IP/域名、备案、反向代理和 HTTPS 等工作不能擅自启动。 + +## 已知风险和待验证事实 + +- 真机上的文件传输和一对一语音通话仍需实际设备验证，不能只根据模拟器结果宣称完成。 +- 手机正式签名、真实员工名单导入和试用前的管理员安全设置，都需要负责人明确确认并由有权限的人执行。 +- 电脑端使用较旧的 Electron，且历史记录提到内网场景的安全取舍；若未来获准公网接入，必须先重新评估 HTTPS、浏览器安全设置、登录限流和跨域策略。 \ No newline at end of file diff --git a/docs/项目需求.md b/docs/项目需求.md new file mode 100644 index 0000000..40276cd --- /dev/null +++ b/docs/项目需求.md @@ -0,0 +1,31 @@ +# 项目需求 + +## 项目是什么 + +“畅联”是集团内部使用的通讯 App，也就是给员工聊天、找同事和语音通话的工具。项目以开源 OpenIM 为基础改造，保留 OpenIM 原有标识，不换品牌、不另起一套产品标识。 + +## 要解决什么 + +员工需要在公司内部使用同一个账号，在手机和电脑上沟通，不依赖个人社交软件。管理员可以把员工名单一次导入，员工用工号和密码登录。 + +## 必须具备的功能 + +1. 聊天：能收发工作消息；当前代码还包含图片、文件和语音消息的相关能力。 +2. 通讯录：能查找同事、添加同事和管理联系人。 +3. 一对一语音通话：通过 LiveKit（负责实时语音连接的服务）建立通话。 +4. 账号登录：员工用“工号 + 密码”登录，不能用个人注册替代。 +5. 管理员导入：管理员能导入员工名单并管理账号。 + +## 支持范围 + +- 手机端：Android 和 iPhone 工程都在仓库中；当前手机端版本号为 `1.0.6+7`。 +- 电脑端：Windows 优先；当前电脑端显示版本为 `v1.0.2`。 +- 服务端：以 Docker Compose（把一组服务一起启动的工具）编排 OpenIM、账号服务和语音服务。 + +## 当前边界 + +- 只做集团内部通讯，不改造成公开社交产品。 +- 保留 OpenIM 的现有标识，禁止替换品牌。 +- 本项目当前只记录和维护内网环境；公网接入尚未获准施工。 +- 不把员工名单、密码、管理员口令、密钥或服务器私密配置写入仓库和文档。 +- 本仓库的日常任务如无明确授权，不做发布、部署或改动生产环境。 \ No newline at end of file