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:

```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`.