Initial Web IM deployment

2026-06-30 10:13:48 +07:00
commit 1cbc3c4cf0
67 changed files with 55851 additions and 0 deletions
@@ -0,0 +1,299 @@
+# JC Web IM Session Handoff
+
+Updated: 2026-05-02 03:18:54 UTC
+
+## Current Goal
+
+Continue the Web IM version under:
+
+```text
+/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:
+
+```text
+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:
+
+```text
+jc-im-server
+jc-app-server
+```
+
+Useful checks:
+
+```bash
+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:
+
+```text
+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:
+
+```text
+[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:
+
+```bash
+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:
+
+```text
+/opt/app-server/config/application.properties
+```
+
+Known important setting:
+
+```properties
+AppCode=676d5adc3ee049b4aeb69f440305c953
+```
+
+Redis was configured locally to accept the password expected by this app-server:
+
+```text
+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:
+
+```text
+/var/www/jc-im/jc-web-im/public/api
+```
+
+Build copies them to:
+
+```text
+/var/www/jc-im/jc-web-im/dist/api
+```
+
+Current PHP APIs:
+
+```text
+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:
+
+```text
+public/api/im_web_bootstrap.php
+```
+
+Current values:
+
+```php
+const IM_ADMIN_URL = 'http://127.0.0.1:18080';
+const IM_ADMIN_SECRET = '123456';
+```
+
+### Contact List API
+
+Endpoint:
+
+```text
+POST /api/contacts.php
+```
+
+Payload:
+
+```json
+{"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:
+
+```text
+POST /api/update_alias.php
+```
+
+Payload:
+
+```json
+{"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:
+
+```text
+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:
+
+```bash
+cd /var/www/jc-im/jc-web-im
+npm run build
+```
+
+Build output included:
+
+```text
+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:
+
+```bash
+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:
+
+```text
+/var/www/jc-im/jc-web-im/WEB_DEPLOYMENT.md
+```
+
+README links to it:
+
+```text
+/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:
+
+```text
+current userId: 58f71e6245e145409e69b30216c6ebad
+```
+
+Contacts returned:
+
+```text
+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`.