# Multi-Address Single Deployment Data Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ensure external and local/LAN access addresses are documented and verified as multiple entrypoints to the same deployment stack and database, not two separately running data sets.

**Architecture:** The application keeps one active Compose stack for formal business data. External and local addresses both route to that stack's Nginx, which forwards `/api/` to the same NestJS server and PostgreSQL volume. `docker-compose.local.yml` remains an independent local/LAN demo stack and must not be described as a synced copy of production data.

**Tech Stack:** Docker Compose, Nginx reverse proxy template, Next.js same-origin API config, Node deployment verifier, Markdown deployment docs.

---

## File Structure

- Modify `scripts/verify-production-deploy.mjs`: add checks that deployment docs and env examples describe multi-address single-stack behavior.
- Modify `.env.production.example`: add comments that `SERVER_NAME` is the primary public host and local/LAN access must route to the same Nginx stack.
- Modify `.env.local-server.example`: add comments that this is an independent local/LAN demo stack, not a synced view of production data.
- Modify `docs/deployment.md`: explain the recommended multi-address single deployment and warn against running prod/local stacks for the same business.
- Modify `docs/architecture.md`: document that one formal business stack may have multiple access addresses.
- Modify `docs/decisions.md`: add a decision that address-level consistency is solved by one active deployment stack, not data sync.
- Modify `docs/workflow.md`: update deployment flow and troubleshooting checks for address routing.

---

### Task 1: Add Deployment Verifier Expectations

**Files:**
- Modify: `scripts/verify-production-deploy.mjs`

- [ ] **Step 1: Add failing verifier snippets**

In `scripts/verify-production-deploy.mjs`, update existing checks so the deployment verifier requires the new wording.

Add these snippets to the `.env.production.example` check:

```js
'Primary public host',
'same Compose Nginx',
```

Add these snippets to the `.env.local-server.example` check:

```js
'independent local/LAN demo stack',
'does not sync with production data',
```

Add these snippets to the `docs/deployment.md` check:

```js
'同一部署多入口访问',
'外网地址和本地地址',
'同一套 Compose',
'不要同时启动',
```

Add these snippets to the `docker-compose.prod.yml` check:

```js
'SERVER_NAME',
'NEXT_PUBLIC_API_URL',
```

Keep all existing checks that still apply.

- [ ] **Step 2: Run verifier to confirm it fails**

Run:

```bash
pnpm deploy:verify
```

Expected: command exits non-zero and prints missing snippets for `.env.production.example`, `.env.local-server.example`, and `docs/deployment.md`.

- [ ] **Step 3: Commit failing verifier**

Run:

```bash
git add scripts/verify-production-deploy.mjs
git commit -m "test(deploy): 覆盖多入口单部署校验"
```

---

### Task 2: Clarify Environment Examples

**Files:**
- Modify: `.env.production.example`
- Modify: `.env.local-server.example`

- [ ] **Step 1: Update production env comments**

In `.env.production.example`, replace:

```env
# Public entrypoint
SERVER_NAME=pm.example.com
```

with:

```env
# Public and local entrypoints
# Primary public host. Local/LAN addresses should route to the same Compose Nginx stack,
# not to a separate docker-compose.local.yml stack, when they need the same business data.
SERVER_NAME=pm.example.com
```

Keep `NEXT_PUBLIC_API_URL=/api/v1`.

- [ ] **Step 2: Update local-server env comments**

In `.env.local-server.example`, replace:

```env
# Copy to .env.local-server for an all-in-one local/LAN deployment.
```

with:

```env
# Copy to .env.local-server for an independent local/LAN demo stack.
# This stack uses local_* volumes and does not sync with production data.
# If external and local addresses must show the same business data, route both addresses to the same production Compose stack instead.
```

- [ ] **Step 3: Run verifier to confirm docs still fail**

Run:

```bash
pnpm deploy:verify
```

Expected: command still exits non-zero because `docs/deployment.md` has not yet been updated.

- [ ] **Step 4: Commit env comments**

Run:

```bash
git add .env.production.example .env.local-server.example
git commit -m "docs(deploy): 标注本地栈不与生产数据同步"
```

---

### Task 3: Update Deployment And Architecture Docs

**Files:**
- Modify: `docs/deployment.md`
- Modify: `docs/architecture.md`
- Modify: `docs/decisions.md`
- Modify: `docs/workflow.md`

- [ ] **Step 1: Add deployment section for multi-address access**

In `docs/deployment.md`, add this section before “本地服务器部署”:

````markdown
## 同一部署多入口访问

如果只是希望外网地址和本地地址看到同一份业务数据，不要启动两套部署栈。正确方式是让外网域名、公网 IP、内网 IP 或本机地址都进入同一套 Compose 的 Nginx。

```text
外网地址和本地地址
  -> 同一套 Compose Nginx
  -> 同一个 web/server
  -> 同一个 PostgreSQL volume
```

生产同域部署保持：

```env
NEXT_PUBLIC_API_URL=/api/v1
```

这样浏览器从哪个地址打开页面，就请求该地址下的 `/api/v1`。只要这些地址最终进入同一个 Nginx/server，数据就是同一份。

不要同时启动 `docker-compose.prod.yml` 和 `docker-compose.local.yml` 来承载同一套正式业务。它们使用不同 volume，会看到两套数据。
````

Use the four-backtick outer fence shown above if copying this plan into another Markdown document, because the section contains nested fences.

- [ ] **Step 2: Clarify local-server deployment is independent**

In `docs/deployment.md`, under “本地服务器部署”, add this paragraph near the top:

```markdown
本地服务器部署是一套独立 local/LAN 演示栈，使用 `local_*` volumes。它适合办公室内网试用或离线演示，不会与云服务器生产数据自动保持一致。如果目标是外网地址和本地地址看到同一份正式业务数据，请使用上面的“同一部署多入口访问”，而不是同时运行两套栈。
```

- [ ] **Step 3: Update architecture production boundary**

In `docs/architecture.md`, under the production deployment layer, add:

```markdown
同一套正式业务部署可以有多个访问入口，例如外网域名、公网 IP、内网 IP 或本机地址。多入口必须进入同一个 Nginx/server/PostgreSQL 栈，才能看到同一份数据。`docker-compose.local.yml` 是独立本地/LAN 演示栈，不能作为生产栈的数据同步副本。
```

- [ ] **Step 4: Add decision record**

In `docs/decisions.md`, append a new decision:

```markdown
## 40. 外网与本地访问地址通过同一部署栈保持数据一致

**问题**：用户希望外网地址和本地/内网地址访问系统时看到同一份业务数据。如果两个地址分别打到 `docker-compose.prod.yml` 和 `docker-compose.local.yml`，就会使用不同 PostgreSQL volume，数据天然分叉。

**决策**：外网地址和本地地址应作为同一套正式业务部署的多个入口，全部路由到同一个 Nginx/server/PostgreSQL 栈。`docker-compose.local.yml` 只用于独立本地/LAN 演示，不承诺与生产数据一致。

**理由**：这是访问入口问题，不是数据同步问题。保持单部署栈可以复用现有 `/api/v1` 同域配置和 `app_data` 乐观锁，避免引入双向同步、冲突合并和数据库复制复杂度。
```

- [ ] **Step 5: Update workflow deployment flow**

In `docs/workflow.md`, in the production deployment flow, add:

```markdown
外网地址和本地地址要看到同一份数据时，必须让两个地址都进入同一套 Compose/Nginx。不要同时用 `docker-compose.prod.yml` 和 `docker-compose.local.yml` 承载同一套业务；本地栈使用 `local_*` volumes，只适合独立演示。
```

Also add this troubleshooting item:

```markdown
如果外网地址和本地地址数据不一致，先检查两个地址是否打到了同一个 `/api/v1/config/ai` 后端和同一个 Compose project；不要先做数据库同步。
```

- [ ] **Step 6: Run verifier and type checks**

Run:

```bash
pnpm deploy:verify
pnpm --filter web type-check
pnpm --filter server type-check
```

Expected:

- `pnpm deploy:verify` prints `Production deployment artifacts verified.`
- Both type-check commands exit 0.

- [ ] **Step 7: Commit docs**

Run:

```bash
git add docs/deployment.md docs/architecture.md docs/decisions.md docs/workflow.md
git commit -m "docs(deploy): 说明多入口访问同一部署数据"
```

---

### Task 4: Final Verification And Reporting

**Files:**
- No file changes expected.

- [ ] **Step 1: Run final verification**

Run:

```bash
pnpm deploy:verify
pnpm --filter web type-check
pnpm --filter server type-check
git status --short
```

Expected:

- `pnpm deploy:verify` exits 0.
- `pnpm --filter web type-check` exits 0.
- `pnpm --filter server type-check` exits 0.
- `git status --short` shows only intentional plan/spec files if they were not committed, otherwise no output.

- [ ] **Step 2: Report operational guidance**

In the final response, include:

```text
外网地址和本地地址要看同一份数据时，只运行一套正式业务 Compose；让所有地址都反代到同一个 Nginx/server/PostgreSQL。
```

Also include:

```text
docker-compose.local.yml 是独立演示栈；如果同时和生产栈运行，会看到两套数据。
```