ftb-project-management/docs/superpowers/plans/2026-07-02-local-cloud-single-source-data.md

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:

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

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

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

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

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

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

'SERVER_NAME',
'NEXT_PUBLIC_API_URL',

Keep all existing checks that still apply.

• Step 2: Run verifier to confirm it fails

Run:

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:

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:

# Public entrypoint
SERVER_NAME=pm.example.com

with:

# 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:

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

with:

# 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:

pnpm deploy:verify

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

• Step 4: Commit env comments

Run:

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 “本地服务器部署”:

## 同一部署多入口访问

如果只是希望外网地址和本地地址看到同一份业务数据，不要启动两套部署栈。正确方式是让外网域名、公网 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:

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

• Step 3: Update architecture production boundary

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

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

• Step 4: Add decision record

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

## 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:

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

Also add this troubleshooting item:

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

• Step 6: Run verifier and type checks

Run:

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:

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:

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:

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

Also include:

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