IM-web-new/SESSION_HANDOFF.md

JC Web IM Session Handoff

Updated: 2026-05-02 03:18:54 UTC

Current Goal

Continue the Web IM version under:

/var/www/jc-im/jc-web-im

The current focus is the contact list and contact detail flow:

• Load contacts quickly.
• Avoid duplicate contact rows.
• Show contact detail fields correctly.
• Allow editing the friend alias / remark name.

Important user instruction:

• Do not modify app-server code.
• Local config may be adjusted to fit the local test environment.
• Web-side code and PHP proxy code may be changed as needed.

Runtime Services

Current local runtime:

im-server: /opt/im-server
app-server: /opt/app-server
web source: /var/www/jc-im/jc-web-im
web dist: /var/www/jc-im/jc-web-im/dist

PM2 process names:

jc-im-server
jc-app-server

Useful checks:

pm2 list
curl -s http://127.0.0.1:18000/api/version
curl -s http://127.0.0.1:18888/
curl -I http://127.0.0.1:8023/

Important ports:

18000 im-server HTTP/API
18080 im-server admin
1883  im-server long connection/MQTT
18888 app-server
8023  Web IM Nginx

App Server Status

Remote app-server was previously pulled from:

[email protected]:/opt/app-server

It is a colleague-modified deployment and is no longer started from a jar. It runs from exploded classes/lib, equivalent to:

java -Dfile.encoding=UTF-8 -Xms256m -Xmx1024m \
  -classpath classes:lib/* cn.wildfirechat.app.Application

Do not change its code unless the user explicitly reverses that instruction.

Current local config was preserved/adapted under:

/opt/app-server/config/application.properties

Known important setting:

AppCode=676d5adc3ee049b4aeb69f440305c953

Redis was configured locally to accept the password expected by this app-server:

Mjfg2U@YZdLx&wmH

Be careful: other Redis clients may need auth if they reconnect.

Contact List Architecture

The Web version currently uses PHP proxy endpoints under:

/var/www/jc-im/jc-web-im/public/api

Build copies them to:

/var/www/jc-im/jc-web-im/dist/api

Current PHP APIs:

contacts.php
update_alias.php
add_contact.php
send_message.php
messages.php
im_web_bootstrap.php

The PHP proxy exists because the browser must not directly carry the im-server admin secret.

Admin config is in:

public/api/im_web_bootstrap.php

Current values:

const IM_ADMIN_URL = 'http://127.0.0.1:18080';
const IM_ADMIN_SECRET = '123456';

Contact List API

Endpoint:

POST /api/contacts.php

Payload:

{"userId":"当前登录用户ID"}

Current logic:

1. Calls im-server admin /admin/friend/list.
2. Calls /admin/user/batch_get_infos.
3. Calls /admin/friend/get_alias for each friend.
4. Returns unique contacts with uid, displayName, mobile, portrait, address, alias.

This was verified to be fast locally, around milliseconds rather than the old 8-10 seconds.

Remark / Alias Update API

Endpoint:

POST /api/update_alias.php

Payload:

{"userId":"当前登录用户ID","targetId":"联系人ID","alias":"备注名"}

Current logic:

1. Validates userId, targetId.
2. Allows empty alias to clear remark.
3. Limits alias to 32 UTF-8 characters.
4. Calls im-server admin /admin/friend/set_alias.

Verified manually:

• Setting alias to 测试备注 succeeded.
• contacts.php returned the new alias.
• Test alias was then cleared back to empty.

Frontend Changes Completed

Files touched for contact details and alias editing:

src/config.js
src/services/httpImClient.js
src/stores/contacts.js
src/components/contacts/ContactPanel.vue
src/styles/base.css
public/api/update_alias.php

Important behavior now:

• contactsApi defaults to /api/contacts.php in production.
• updateAliasApi defaults to /api/update_alias.php in production.
• HttpImClient.getServerContactList() maps address and alias.
• HttpImClient.updateContactAlias() posts to the PHP proxy.
• contacts.updateContactAlias() updates local contact state immediately after successful save.
• Contact detail display is:
  • avatar / portrait
  • remark name from t_friend._alias; if empty, show 未设置
  • username from _display_name
  • mobile from _mobile
  • address from _address; if empty, show 未知
• A ✏️ button appears next to the remark name. Clicking it opens a modal to edit the remark.

Build / Deploy Status

Last successful build:

cd /var/www/jc-im/jc-web-im
npm run build

Build output included:

dist/js/app.28165923.js
dist/css/app.08b643a5.css
dist/api/update_alias.php

Build warnings were only webpack asset-size warnings for chunk-vendors, not functional errors.

Syntax checks passed:

php -l jc-web-im/public/api/update_alias.php
php -l jc-web-im/dist/api/update_alias.php

Deployment Documentation

Deployment doc has been added:

/var/www/jc-im/jc-web-im/WEB_DEPLOYMENT.md

README links to it:

/var/www/jc-im/jc-web-im/README.md

Key deployment note:

• Production needs Nginx + PHP-FPM.
• PHP minimum recommended version: 7.4.
• PHP recommended versions: 8.1 / 8.2 / 8.3.
• Required PHP extensions: curl, mbstring.
• Nginx root should point to /var/www/jc-im/jc-web-im/dist.
• 18080 admin port should not be exposed publicly.

Known Current Test User Data

Recent contact list test used:

current userId: 58f71e6245e145409e69b30216c6ebad

Contacts returned:

FireRobot
571356e9237c460698329c1653d6fd63  用户5050  183019202118
55737875bf7a4d089102cbba03b1a8b8  用户8592  18301902118

Both human contacts had empty alias after the manual test was restored.

Suggested Next Steps

Good continuation points:

1. Open the Web page on port 8023 and manually confirm the alias edit modal in the browser.
2. Check whether the contact header should also show the ✏️ edit control or only the profile card should show it.
3. Continue message send/sync polish if contact flow is accepted.
4. Consider optimizing contacts.php alias loading if a user has many friends, because it currently calls get_alias once per friend.

Do Not Forget

• Do not modify /opt/app-server code.
• If changing PHP proxy admin secret or admin URL, update source under public/api and rebuild.
• If editing runtime config after build, check both public/config/runtime-config.js and dist/config/runtime-config.js depending on whether the change should survive future builds.
• The current workspace is /var/www/jc-im, not the old /var/www/im-web.