docs: 同步 Docker 编排说明并补充重构计划与 UI 参考

- README 与 docker/README 更新双 compose 文件说明：docker-compose.yml 仅主应用、docker-compose.full.yml 完整栈
- 新增 docs/superpowers/plans 800 行重构实施计划，规划前后端代码体量护栏与按职责拆分路径
- 新增 docs/ui-mockups 附件关联企业版 UI 参考稿

docker/README.md

@@ -1,67 +1,127 @@
-# Docker Compose
-
-This project currently uses the Vite `__setup/*` middleware during the initial setup flow.
-Because of that, the Docker deployment keeps the web frontend and FastAPI startup chain in
-the same main container and runs the existing root `start.sh`.
-
-## Start
-
-```bash
-cp .env.example .env
-docker compose up -d
-```
-
-Open:
-
-```text
+# Docker Compose
+
+X-Financial 现在按运行依赖分成两层 Docker Compose：
+
+- `docker-compose.yml`：只启动主应用容器，适合已经有远端 PostgreSQL、ONLYOFFICE 或 Qdrant 的环境。
+- `docker-compose.full.yml`：启动完整本地开发栈，适合没有外部依赖、希望本机一次性跑齐所有服务的环境。
+
+主应用容器仍然同时启动 Web 前端和 FastAPI 后端，并复用根目录 `start.sh`。
+项目根目录会挂载到容器内 `/app`。
+
+## 轻量启动：只跑主应用
+
+适合你已经有数据库和 ONLYOFFICE 的情况。
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+默认只会启动：
+
+```text
+main
+```
+
+打开：
+
+```text
 http://<your-linux-host>:5273
-```
-
-## Container Layout
-
-- `main`: web + FastAPI main container
-- `onlyoffice`: ONLYOFFICE Document Server
-- `postgres`: PostgreSQL database container
-
-The project root is mounted directly into the main container:
-
-```text
-.:/app
-```
-
-That means the container reads your existing `.env`, source code, `server/.secrets`, logs,
-and generated dependency directories directly from the mapped project folder.
-
-This is a `compose`-only setup. There is no custom `Dockerfile`.
-The tradeoff is that the `main` container installs the Python runtime packages it needs
-when it starts.
-
-## Persistence
-
-The PostgreSQL data directory is stored in the named volume `postgres_data`.
-
-## Notes
-
-- Most configuration should be maintained in the project root `.env`.
-- The first `docker compose up -d` does not require an existing `.env`; the compose file
-  uses built-in defaults for the PostgreSQL container and the main container database URL.
-- Docker Compose only overrides a few values that must differ inside containers:
-  - `WEB_HOST=0.0.0.0`
-  - `SERVER_HOST=0.0.0.0`
-  - `POSTGRES_HOST=postgres`
-  - `POSTGRES_PORT=5432`
-  - `DATABASE_URL=...@postgres:...`
-- PostgreSQL is also published to the host by default as `127.0.0.1:55432`.
-- ONLYOFFICE is published to the host by default as `127.0.0.1:8082`.
-- First boot with `SETUP_COMPLETED=false` starts the setup UI only.
-- After you complete setup in the browser, the Vite setup bridge will start FastAPI in the
-  same container using the saved runtime configuration.
-- On later restarts, `start.sh` will detect the saved setup state and start both web and
-  server automatically.
-- If you access the system from another machine, make sure `CORS_ORIGINS` in `.env` includes
-  the frontend address you actually use.
-- For Navicat or any host-side client, use `127.0.0.1:55432`.
-- If you need to access ONLYOFFICE from another machine, override `ONLYOFFICE_PUBLIC_URL`
-  so the browser can reach the document server address you actually expose.
-- For the setup page, using `127.0.0.1` is acceptable in this Docker layout; the internal
-  test bridge will resolve that back to the Docker PostgreSQL service.
+```
+
+这条路径不会主动拉起本地 PostgreSQL、Qdrant 或 ONLYOFFICE。
+数据库、ONLYOFFICE 和 Qdrant 地址都从 `.env` 或外部环境变量读取。
+
+常见外部依赖变量：
+
+```text
+DATABASE_URL
+POSTGRES_HOST
+POSTGRES_PORT
+ONLYOFFICE_ENABLED
+ONLYOFFICE_PUBLIC_URL
+ONLYOFFICE_BACKEND_URL
+QDRANT_URL
+```
+
+## 完整启动：本地全栈
+
+适合没有远端数据库和 ONLYOFFICE 的情况。
+
+```bash
+docker compose -f docker-compose.full.yml up -d
+```
+
+会启动：
+
+```text
+main
+postgres
+qdrant
+onlyoffice
+```
+
+本地服务端口：
+
+```text
+Web:        5273
+FastAPI:    8000
+PostgreSQL: 55432 -> 5432
+Qdrant:     6333 / 6334
+ONLYOFFICE: 8082
+SSH:        2223
+```
+
+完整栈会把主容器内的数据库地址指向 `postgres:5432`，
+并把 Qdrant 地址指向 `http://qdrant:6333`。
+
+ONLYOFFICE 默认使用本机可访问地址：
+
+```text
+http://127.0.0.1:8082
+```
+
+如果浏览器从另一台机器访问，需要覆盖：
+
+```bash
+LOCAL_ONLYOFFICE_PUBLIC_URL=http://<host>:8082 \
+docker compose -f docker-compose.full.yml up -d
+```
+
+如果 ONLYOFFICE 回调后端也需要外部地址，可以同时覆盖：
+
+```bash
+LOCAL_ONLYOFFICE_BACKEND_URL=http://<host>:8000 \
+docker compose -f docker-compose.full.yml up -d
+```
+
+## 可选：只额外启动本地 PostgreSQL
+
+如果只想在轻量主容器旁边补一个本地 PostgreSQL，可以使用覆盖文件：
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d
+```
+
+这会启动：
+
+```text
+main
+postgres
+```
+
+## 停止与清理
+
+停止当前默认轻量栈：
+
+```bash
+docker compose down
+```
+
+停止完整本地栈：
+
+```bash
+docker compose -f docker-compose.full.yml down
+```
+
+如需删除本地数据卷，先确认不再需要其中数据，再手动执行带 `-v` 的清理命令。