# 联网前部署方案

NexaOffice 继续采用 **local-first / offline-first** 设计：没有系统部署配置时，桌面端不会自动联网；服务器信息由管理员或部署文件统一下发，不给普通用户手动填写 Token。

## 桌面端配置方式

后续部署服务器后，可以使用以下任意一种方式配置：

1. EXE 同目录：`nexaoffice_server.json`
2. 用户数据目录：`data/system_server_config.json`
3. 环境变量：
   - `NEXA_SERVER_URL`
   - `NEXA_WORKSPACE_ID`
   - `NEXA_API_TOKEN`
   - `NEXA_AUTO_CONNECT`
   - `NEXA_SYNC_EVENTS`

普通用户界面只显示系统连接状态，不暴露 Token、内部 workspace id 和完整请求地址。

## v2026.06.20.80 服务端契约

服务端准备目录：`server/`

当前基础接口：

- `GET /health`
- `GET /api/health`
- `POST /api/bootstrap`
- `POST /api/sync`
- `POST /api/sync/batch`
- `POST /api/contacts/register`
- `POST /api/contacts/resolve`

其中 `POST /api/bootstrap` 只做上线前契约确认：返回支持的 scope、批量大小、字段要求，不会返回 Token。

`POST /api/sync/batch` 用于未来批量同步准备，当前仍是安全的 JSONL 存储雏形，正式多人生产前需要替换为数据库和权限模型。

## 个人版 / 企业版隔离要求

未来服务器必须同时遵守客户端隔离：

- 每条同步数据必须带 `scope`：`personal` 或 `enterprise`
- Personal 模式不能读取 enterprise 数据
- Enterprise 模式不能读取 personal 数据
- Chat、Cloud、Enterprise 通知和快捷入口必须随当前模式隔离
- Token 不允许写入日志、UI 或诊断报告

## 推荐部署流程

1. 部署 `server/`，确认 `/health` 正常
2. 配置 HTTPS 域名；本地测试才允许 localhost HTTP
3. 复制 `server_config.template.json` 为 `nexaoffice_server.json`
4. 填入 `base_url`、`workspace_id`、`api_token`
5. 保持 `managed_by_system=true`、`user_configurable=false`
6. 先运行自检：
   - `python tools/system_server_config_check.py --write-report`
   - `python tools/network_deployment_plan_check.py`
   - `python tools/server_deployment_readiness_check.py`
7. 确认 dry-run 报告 OK 后，再开启 `auto_connect`

## 安全原则

- 没有系统服务器配置时不自动联网
- 正式服务器优先 HTTPS
- HTTP 只允许 localhost 测试
- Token 不显示、不进入日志
- 同步队列控制体积，避免未来联网后启动变慢
- 上线前必须先通过 cutover dry-run
