Files

T

编码工程师andmultica-agent 6cd369f548 docs: add project handover handbook

Co-authored-by: multica-agent <github@multica.ai>

2026-08-23 14:28:07 +08:00

8.2 KiB

Raw Permalink Blame History

⚠️ 本文档已过时，仅留档备查，请勿删除。当前请先看 docs/README.md、docs/项目需求.md、docs/最新进度.md 和 docs/任务清单.md。

第4步 · 试用前部署与验收清单（B-61）

本文件记录"50 人试用"前必须在服务器上手动完成的事项、验收清单与手机正式签名流程。仓库代码与本文件已就绪；下列所有"服务器上做"的动作都要等白栖知确认后再执行，本轮不直接改现网。

1. 必须由白栖知确认后执行的服务器操作

1.1 管理员强口令（必做，试用前）

账号服务的管理页 http://<服务器IP>:10010/ 现在默认口令是 admin123，谁都能改账号，必须改掉。

在服务器仓库目录（tongxunruanjian/）里：

# 1) 把 .env 里的管理口令改成一个自己记得住的强口令
#    编辑 .env，找到 ACCOUNT_ADMIN_TOKEN=admin123，改成如：ACCOUNT_ADMIN_TOKEN=Changlian@2026
# 2) 重建账号服务使生效
docker compose up -d --build account-server

验证：浏览器打开管理页，用新口令能登录；旧口令 admin123 提示错误。

1.2 导入 50 人名单并确认持久化（必做）

账号数据存在服务器 tongxunruanjian/data/account/employees.json（已挂载卷，重建容器不丢）。质检审核发现现网账号库目前只有 2 个测试账号，试用前需重新导入 50 人真实名单。

步骤：

准备 CSV：每行 工号,姓名,初始密码（Excel 可先存 CSV）。工号限字母/数字/-/_，2-32 位；密码至少 6 位。管理页有"模板下载"按钮，直接按模板填。
打开管理页 → 粘贴/选择 CSV 导入，确认导入成功数 = 50。

到服务器确认文件真落盘了：

ls -l tongxunruanjian/data/account/employees.json
grep -c '"hash"' tongxunruanjian/data/account/employees.json   # 应为 50

抽查：用某个员工的工号+密码在手机端/电脑端各登录一次。

注意：导入的 50 人名单 = 真实员工数据，必须等白栖知明确同意后再导。

1.3 手机正式签名（试用分发前准备，可由用户保管）

当前手机端 release 包用的是调试签名，之后换正式签名会导致已装用户要卸载重装，所以趁试用期只有小范围用户，先切到正式签名。

签名密钥绝不提交仓库，由白栖知自行保管。流程（一次性准备，在开发机上做）：

# 1) 生成自签证书（keytool 随 JDK 自带），口令自己设并记牢，别忘
keytool -genkeypair -v -keystore changlian-release.jks \
  -alias changlian -keyalg RSA -keysize 2048 -validity 36500 \
  -storepass <你的口令> -keypass <你的口令> \
  -dname "CN=Changlian, OU=IT, O=Company, L=City, ST=State, C=CN"

# 2) 把密钥库放到安全位置（建议不放代码目录），并在本机新建
#    mobile/android/key.properties（已被 .gitignore 忽略，不会入库）：
#    storePassword=<你的口令>
#    keyPassword=<你的口令>
#    keyAlias=changlian
#    storeFile=<changlian-release.jks 的绝对路径>

# 3) mobile/android/app/build.gradle.kts 的 release 块已留 TODO：
#    signingConfig 目前指向 debug，改成读 key.properties 的正式签名后，
#    执行 flutter build apk --release 即可出正式签名包。

参考 mobile/android/app/build.gradle.kts release 块注释（R8 混淆必须保持关闭，与官方样板一致，OpenIM 插件靠反射分发调用，混淆会静默失效）。

1.4 外网访问（按需，需白栖知明确确认）

若只内网试用：跳过本节。
若要让手机流量也能用：需要 ① 公网 IP 或域名 ② ICP 备案 ③ 反代 + HTTPS 证书（服务器上 nginx/caddy 都可，把 :10001/:10002/:10005/:10010/:17880 反向代理到外网域名）。这一步必须先经白栖知拍板再动，且涉及实名备案资料，无法代办。

2. 真机 + 跨端回归清单（试用前执行，逐项打勾）

说明：本轮在开发环境已完成代码级验证（见下方"已完成的自测"）；下表为需两台真机/PC 参与的联调项，由白栖知组织 1~2 人配合执行。

A. 登录与基础

手机（安卓）装 changlian-1.0.5-android-arm64.apk，工号+密码能登录
电脑装 畅联_1.0.1.exe，同一工号+密码能登录
两个不同工号同时登录，互不干扰
输错密码 3 次有提示（登录接口无失败限制，仅提示）

B. 文字消息（手机↔PC 互发）

手机发文字 → PC 实时收到，排序正确
PC 发文字 → 手机实时收到
长文本（几百字）、特殊字符（emoji、括号、引号）不丢字不乱码
群聊：建一个 3 人群，三端消息同步

C. 语音消息

手机发语音条 → PC 能听到，时长正确，已听红点消失
PC 发语音条 → 手机能听到
语音条连续发多条，顺序不乱

D. 文件

手机传文件（如 1 张图片）→ PC 能下载打开
PC 传文件 → 手机能下载打开
大文件（≥50MB，OpenIM/MinIO 上限内）传输成功
断网后发送显示红色感叹号，点重发能成功

E. 语音通话

手机 ↔ PC 一对一语音通话接通，声音双向清晰
挂断正常，会话列表不残留"通话中"
手机断网/切后台再回，通话状态不假死

F. 管理端

管理员停用一个账号 → 该账号手机/PC 立即被踢下线、无法再登录
管理员重置某账号密码 → 该账号已登录端被踢下线，新密码能登录（本轮已加"重置密码踢下线"，需真实验证一次）
管理页能翻看 50 人列表

3. 已完成的自测记录（本轮，代码层验证）

PC 安装包：pc-client 全新 npm install 通过（husky 在非 ASCII 路径下不再阻断，回退提示中文）；npm run build exit 0；npx electron-builder --win --x64 产出 畅联_1.0.1.exe（约 101MB）；win-unpacked 双击启动正常（冒烟通过）。
类型检查：tsc --noEmit 24 个错误，与基线 2fe8417 完全一致（均为工程原有问题），本次改动未新增。
头像/拼格/Token 收敛：改动已进 dist（构建产物中可查到 v1.0.1、avatar-gray、chat-bg、call-wait-bg）。
重置密码踢下线：起本地账号服务（临时数据文件，连测试 OpenIM）验证——员工登录拿到 token → 管理端重置密码 → 原 token 再调 OpenIM parse_token 返回 TokenKickedError；旧密码登录失败、新密码登录成功。✓

4. 改动清单（本 commit）

pc-client/src/components/OIMAvatar/index.tsx：中文名头像取首字（王志远→王，与手机端一致）；群头像无真实图时改为 2×2 蓝灰拼格（浅灰底 + 蓝/灰蓝交替），加载失败同样回退拼格。
pc-client/src/styles/global.scss：新增 --avatar-gray、--search-bg、--chat-bg、--call-wait-bg 四个 Token。
收敛近似灰为统一 Token：#F3F5F7（聊天区底/hover/搜索框）→ var(--chat-bg)；#F4F5F7（设置页分隔块）→ var(--chat-bg)；#F2F8FF（呼叫等待底）→ var(--call-wait-bg)。全 pc-client/src 无新硬编码色残留。
account-service/server.js：reset_password 重置密码后调用 forceLogoutAll 踢掉该员工所有端（与停用/删除一致）。
pc-client/package.json / package_electron.json：prepare: husky install 改为 husky install || true 容错，非 ASCII/嵌套路径下 npm install 不再失败。
pc-client/README.md：补充 husky 容错说明与新安装包版本。
pc-client/package.json / src/config/index.ts：版本号 1.0.0 → 1.0.1，与新的验收安装包对应（旧 畅联_1.0.0.exe 作废）。

5. 已知事项

双端服务器地址仍烧死为 192.168.200.11（mobile lib/config.dart、pc .env），换服务器 IP 需双端重打包，见质检审核员备注。
Electron 22 偏旧 + webSecurity: false：内网 HTTP 场景可接受；若开外网必须先升级并开 HTTPS。
IM token 明文存本地、登录无失败次数限制、CORS 全开：内网单人管理可接受，开外网时随 HTTPS 一并收紧。

8.2 KiB Raw Permalink Blame History Unescape Escape