chore(devops): 本地/compose 宿主端口 +1000 防冲突（web 4000 / api 9000 / pg 6432）+ 文档登记

CLAUDE.md

@@ -127,7 +127,7 @@ Aligns `ARCHITECTURE.md §9.3`. This is how every failure gets diagnosed.
 
 - **环境变量**：`uv` 装到 `~/.local/bin`，命令前 `export PATH="$HOME/.local/bin:$PATH"`。
 - **依赖安装**：`uv sync`（后端，仓库根）；`pnpm install`（前端，`cd apps/web`）。
-- **本地起服务**：`docker compose up`（pg + api + web）。仅起库：`docker compose up -d pg`。裸跑 API：`uv run uvicorn ww_api.main:app --reload`。
+- **本地起服务（宿主端口 +1000 防冲突：web 4000 / api 9000 / pg 6432；容器内仍 3000/8000/5432）**：`docker compose up`（pg + api + web，端口已 +1000）。仅起库：`docker compose up -d pg`（宿主 6432）。裸跑：API `uv run uvicorn ww_api.main:app --port 9000 --reload`（读根 `.env`→pg 6432 / CORS 放行 4000）；前端 `cd apps/web && pnpm dev`（`next dev -p 4000`，读 `apps/web/.env.local`→`NEXT_PUBLIC_API_BASE=http://localhost:9000`）。`.env`/`.env.local` 为本机文件（gitignored）。
 - **迁移**：`uv run alembic upgrade head`；改模型后 `uv run alembic revision --autogenerate -m "..."`；漂移校验 `uv run alembic check`（需 pg 在跑）。
 - **后端门禁**：`uv run ruff check .` · `uv run ruff format .` · `uv run mypy packages apps` · `uv run pytest -q`。覆盖率门禁：`uv run pytest -q --cov --cov-report=term-missing --cov-fail-under=80`。单测：`uv run pytest path::test -q`（单测不带 `--cov`，避免 fail-under 误报）。
 - **前端门禁**（`cd apps/web`）：`pnpm lint` · `pnpm typecheck` · `pnpm test`（vitest）· `pnpm build`。覆盖率门禁：`pnpm test:coverage`（阈值 80%，范围 `lib/**`）。

README.md

@@ -43,6 +43,8 @@
 
 前置：Python 3.12+ · Node 22 · [uv](https://docs.astral.sh/uv/) · pnpm · Docker
 
+> **本地端口（宿主已 +1000，防与其他项目冲突）**：前端 **http://localhost:4000** · 后端 **http://localhost:9000**（API 文档 `/docs`）· Postgres **localhost:6432**。容器内部端口不变（3000 / 8000 / 5432），只改宿主发布端口；要改回默认各减 1000 即可。接线：前端 `apps/web/.env.local` 的 `NEXT_PUBLIC_API_BASE=http://localhost:9000` 指向后端；后端 `.env` 的 `CORS_ORIGINS` 放行 `http://localhost:4000`、`DATABASE_URL` 指向 `localhost:6432`。
+
 ```bash
 # 1. 克隆后，安装后端依赖（仓库根，uv workspace）
 uv sync
@@ -59,17 +61,17 @@ cp .env.example .env
 docker compose up -d pg
 uv run alembic upgrade head
 
-# 5. 起后端 API（默认 http://localhost:8000，文档 /docs）
+# 5. 起后端 API（http://localhost:9000，文档 /docs）— 宿主端口 +1000
-uv run uvicorn ww_api.main:app --reload
+uv run uvicorn ww_api.main:app --port 9000 --reload
 
-# 6. 起前端（另开终端，默认 http://localhost:3000）
+# 6. 起前端（另开终端，http://localhost:4000）— pnpm dev 已内置 -p 4000
 cd apps/web && pnpm dev
 ```
 
-或一键起全套（pg + api + web）：
+或一键起全套（pg + api + web，宿主端口均已 +1000）：
 
 ```bash
-docker compose up
+docker compose up   # web → :4000 · api → :9000 · pg → :6432
 ```
 
 > **LLM API Key 不放 `.env`**：在应用设置页 **`/settings/providers`** 录入，密文存于数据库凭据库（用 `CREDENTIAL_ENC_KEY` 加密）。`.env` 里只有那把加密主密钥本身。

apps/web/package.json

@@ -3,9 +3,9 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev -p 4000",
     "build": "next build",
-    "start": "next start",
+    "start": "next start -p 4000",
     "lint": "next lint",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

docker-compose.yml

@@ -5,8 +5,9 @@ services:
       POSTGRES_USER: writer
       POSTGRES_PASSWORD: writer
       POSTGRES_DB: writer
+    # 宿主端口 +1000 防与其他项目冲突（容器内仍 5432）。
     ports:
-      - "5432:5432"
+      - "6432:5432"
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U writer"]
       interval: 5s
@@ -24,12 +25,13 @@ services:
       DATABASE_URL_SYNC: postgresql+psycopg://writer:writer@pg:5432/writer
       APP_ENV: ${APP_ENV:-dev}
       LOG_JSON: ${LOG_JSON:-false}
-      CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:3000,http://127.0.0.1:3000}
+      CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:4000,http://127.0.0.1:4000}
       # Fernet 加密 key：api 启动即校验，缺失/非法则拒绝启动。compose 自动读根 .env 覆盖此默认；
       # 默认值 = .env.example 的 dev 占位 key，保证 `docker compose up` 无 .env 也能起（勿用于生产）。
       CREDENTIAL_ENC_KEY: ${CREDENTIAL_ENC_KEY:-cnMpG6QQxJejuDLHTe_S-nq2snoKgXCqWFfsctEHB-4=}
+    # 宿主端口 +1000 防冲突（容器内仍 8000）。
     ports:
-      - "8000:8000"
+      - "9000:8000"
     depends_on:
       pg:
         condition: service_healthy
@@ -39,13 +41,14 @@ services:
       context: ./apps/web
       # NEXT_PUBLIC_API_BASE 为构建期内联，须经 build arg 传入（见 apps/web/Dockerfile）。
       args:
-        NEXT_PUBLIC_API_BASE: ${NEXT_PUBLIC_API_BASE:-http://localhost:8000}
+        NEXT_PUBLIC_API_BASE: ${NEXT_PUBLIC_API_BASE:-http://localhost:9000}
     environment:
-      NEXT_PUBLIC_API_BASE: ${NEXT_PUBLIC_API_BASE:-http://localhost:8000}
+      NEXT_PUBLIC_API_BASE: ${NEXT_PUBLIC_API_BASE:-http://localhost:9000}
-      # RSC 服务端取数走容器内网直连 api（否则回退 localhost:8000 打不到 api 容器）。
+      # RSC 服务端取数走容器内网直连 api（否则回退打不到 api 容器）。
       API_BASE_INTERNAL: http://api:8000
+    # 宿主端口 +1000 防冲突（容器内仍 3000）。
     ports:
-      - "3000:3000"
+      - "4000:3000"
     depends_on:
       - api