feat(GOV-006): 建立环境配置与双部署基线

2026-08-13 10:54:55 +08:00
parent 4ce33d8c7d
commit 9203fdd0c2
43 changed files with 846 additions and 11 deletions
@@ -47,3 +47,12 @@ tools/      可重复执行的治理和开发工具
 ## 4. 当前实施顺序

 第一阶段先实现可交互的市场综合概览和稳定数据契约，再接入正式行情采集链路。用户、邀请、权限、会员和支付后置，不进入当前核心架构。
+
+## 5. 环境与部署基线
+
+- 应用运行环境只定义 `development` 与 `production`；生产环境禁止模拟数据、热更新、调试端口和开发默认值回退。
+- API、Scheduler、Worker、Web 分别拥有开发和生产模板；同一进程跨环境使用相同变量名，通过启动 Schema 校验条件必填项。
+- 本地开发使用 Docker Compose 只启动 Redis，应用进程从源码运行；第一阶段 MySQL 与 RabbitMQ 保持关闭。
+- 生产同时支持 Docker Compose 和 Ubuntu 22.04/24.04 LTS x86_64 源码部署，两者共用配置契约和进程边界。
+- 源码部署由管理员预装 Node.js 22 LTS、pnpm 10、Nginx 和基础设施；项目只验证，不安装或修改系统软件源。
+- 源码部署使用不可变发布目录、`a-share` 用户和 systemd 独立进程配置；生产 env 存放在 `/etc/a-share-analysis/`，不随代码版本切换覆盖。
@@ -0,0 +1,18 @@
+# Docker Compose 生产部署
+
+生产 Docker Compose 使用不可变应用镜像和外部 env 文件。当前 `production.yml.example` 是部署契约骨架，应用镜像、健康检查和实际启动命令必须在 Web/Server 脚手架完成后验证，未验证前不得用于线上部署。
+
+## 配置边界
+
+- 从 `deploy/env/production/` 准备四份真实配置，存放在服务器 `/etc/a-share-analysis/` 或其他受控目录。
+- Compose 通过外部路径加载，不在 YAML、镜像和 Git 中保存秘密。
+- 镜像引用必须包含版本或内容摘要，禁止浮动 `latest`。
+- 第一阶段只依赖 Redis；MySQL 和 RabbitMQ 功能开关保持关闭。
+
+## 发布与回退
+
+部署前验证镜像对应已推送提交或标签、环境 Schema、健康检查和数据目录。升级只修改不可变镜像引用；失败时恢复上一完整镜像集合和未改变的外部配置。禁止删除 Redis、MySQL 或 RabbitMQ 数据目录作为应用回退手段。
+
+## 验证
+
+应用脚手架落地后必须补充 `docker compose config`、服务健康检查、日志读取、优雅停止和回退演练证据。本版本不声称生产 Compose 已可运行。
@@ -0,0 +1,21 @@
+# 本地开发环境
+
+本地开发使用 Docker Compose 只启动 Redis，Web、API、Scheduler 和 Worker 从源码运行并使用开发环境模板。第一阶段不启动 MySQL 和 RabbitMQ。
+
+## 配置
+
+从 `deploy/env/development/` 中对应的 `*.env.example` 创建本机 `*.env.local`。真实文件被 Git 忽略，不得写入生产地址或真实密钥。
+
+## Redis
+
+```bash
+docker compose -f deploy/compose/development.yml up -d
+docker compose -f deploy/compose/development.yml ps
+docker compose -f deploy/compose/development.yml down
+```
+
+Redis 只绑定 `127.0.0.1:6379`，数据写入仓库忽略的 `.local/redis/`。不得把该 Compose 文件用于生产。
+
+## 应用状态
+
+Web 和 Server 尚未完成脚手架，因此本版本只交付配置契约和 Redis 开发环境。后续脚手架必须使用 Node.js 22 LTS、pnpm 10 和这些模板，不能在本文档中假装应用已经可启动。
@@ -0,0 +1,35 @@
+# Ubuntu 源码生产部署
+
+正式支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS 的 x86_64。服务器管理员预先提供 Node.js 22 LTS、pnpm 10、Nginx，以及 MySQL 5.7、Redis、RabbitMQ 或相应外部服务；项目不负责安装或升级这些软件，也不修改系统软件源。
+
+## 前置验证
+
+```bash
+uname -m
+node --version
+pnpm --version
+nginx -v
+```
+
+架构必须为 `x86_64`，Node.js 必须为 22 LTS，pnpm 必须为 10.x。不满足要求时终止部署。
+
+## 目录与配置
+
+- 发布目录：`/opt/a-share-analysis/releases/<版本或提交>/`。
+- 当前版本：`/opt/a-share-analysis/current` 符号链接。
+- 生产配置：`/etc/a-share-analysis/api.env`、`scheduler.env`、`worker.env`、`web.env`。
+- 运行用户：非登录系统用户 `a-share`。
+
+真实配置从仓库生产模板生成，但不得放入发布目录。API、Scheduler、Worker 的 systemd 单元分别通过 `EnvironmentFile=` 读取自己的配置；包含秘密的文件建议为 `root:a-share 0640`。
+
+## 构建与启动边界
+
+使用 `pnpm install --frozen-lockfile` 安装锁定依赖，在新发布目录构建 Web 和 Server。Web 静态文件由 Nginx 托管，API、Scheduler、Worker 运行编译后的 JavaScript。禁止 Vite 开发服务器、watch、调试端口和生产运行 TypeScript。
+
+当前应用尚未脚手架化，仓库中的 systemd 与 Nginx 文件是路径和权限契约示例，不能冒充已经验证的线上启动文件。后续应用功能必须补充实际构建、启动和健康检查验证。
+
+## 升级、检查与回退
+
+在新的不可变发布目录完成安装、构建和配置校验后，原子切换 `current`，依次重启 API、Scheduler、Worker 并检查 `systemctl status`、`journalctl` 和 HTTP 健康端点。失败时切回上一完整目录并重启服务；生产配置不随版本切换覆盖。
+
+项目部署流程禁止连接或读取生产数据库做开发验证。数据库备份属于独立运维职责，应用回退不得删除或覆盖数据。
@@ -0,0 +1,9 @@
+# GitNexus 开发后结果
+
+- 执行：`npx gitnexus analyze`。
+- 工作区索引：620 个节点、651 条关系、7 个集群、0 条执行流程。
+- 增量分析：7 个已修改文件、25 个新增文件、0 个删除文件。
+- 当前索引提交：`4ce33d8`；配置和文档变化已进入增量图谱。
+- 状态：up-to-date。
+
+实现提交后再次分析并锚定最终提交。
@@ -0,0 +1,10 @@
+# GitNexus 前后对比
+
+| 项目 | 开发前 | 开发后工作区 | 变化 |
+|---|---:|---:|---:|
+| 节点 | 452 | 620 | +168 |
+| 关系 | 477 | 651 | +174 |
+| 集群 | 5 | 7 | +2 |
+| 执行流程 | 0 | 0 | 0 |
+
+新增集群来自环境模板与部署文档边界；没有生产执行流程变化，符合影响预估。
@@ -0,0 +1,8 @@
+# GitNexus 变更检测
+
+- 命令：`npx gitnexus detect-changes --repo a-share-analysis --scope staged`。
+- 最终暂存区：43 个文件、77 个符号。
+- 受影响流程：0。
+- 风险等级：低。
+
+范围包含配置模板、Compose、systemd、Nginx、部署文档、现行治理入口、契约测试和 GOV-006 档案。
@@ -0,0 +1,7 @@
+# GitNexus 开发前影响分析
+
+- 查询主题：`development production environment templates Docker Compose Ubuntu source deployment systemd`。
+- 关联范围：README、开发流程、开发规范、系统架构、GOV-005 和部署目录。
+- 本次新增配置、文档和静态测试，不修改既有生产函数、类或方法，无生产符号上游影响目标。
+- GitNexus 未识别业务执行流程；预计影响限于配置契约、部署边界和治理测试。
+- 风险控制：不提交真实秘密，不运行应用部署，不连接任何生产服务，明确示例骨架的未验证状态。
@@ -0,0 +1,129 @@
+# 开发、生产环境与双部署方式实施计划
+
+> **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:** 建立可机器验证的开发/生产环境变量契约、本地 Redis Compose，以及 Docker Compose 与 Ubuntu 源码生产部署规范和配置骨架。
+
+**Architecture:** 八份 env 模板按进程和环境分离，但同一进程在 development/production 使用相同变量名。静态契约测试负责检查模板完整性、敏感值为空、Web 仅暴露 `VITE_*`、生产安全默认值和部署文件边界；当前应用尚未实现，不伪造可运行的应用镜像或启动命令。
+
+**Tech Stack:** dotenv 模板、Docker Compose、Redis、systemd、Nginx、Node.js 内置测试运行器、Markdown、GitNexus。
+
+## Global Constraints
+
+- 环境仅定义 `development` 与 `production`，生产禁止模拟数据、热更新和开发默认值回退。
+- 仓库提交八份 `*.env.example`，不提交任何真实 `.env` 或凭据。
+- 本地 Compose 只启动 Redis；Web/API/Scheduler/Worker 从源码运行。
+- 生产支持 Docker Compose 和 Ubuntu 22.04/24.04 x86_64 源码部署。
+- Node.js 22 LTS、pnpm 10、Nginx 和基础设施由管理员提供，项目只验证不安装。
+- 源码部署使用 `a-share` 用户和 `/etc/a-share-analysis/*.env`。
+- MySQL 与 RabbitMQ 第一阶段默认关闭；MySQL 条件配置遵守 GOV-005。
+
+---
+
+### Task 1: 建立失败的环境配置契约测试
+
+**Files:**
+- Create: `tools/governance/environment-baseline.test.mjs`
+- Modify: `package.json`
+
+**Interfaces:**
+- Consumes: `deploy/env/`、`deploy/compose/`、`deploy/systemd/`、`deploy/nginx/` 和 `docs/deployment/`。
+- Produces: `npm run test:environment-baseline`。
+
+- [ ] **Step 1: 编写模板和部署边界测试**
+
+测试八份模板存在、同一进程两环境键集合相同、敏感键为空、Web 仅含 `VITE_*`、生产安全开关正确、本地 Compose 仅定义 Redis，并检查 systemd/Nginx 与两份生产部署文档。
+
+- [ ] **Step 2: 验证测试因文件缺失而失败**
+
+运行：`npm run test:environment-baseline`
+
+预期：失败明确指出第一份缺少的环境模板或部署文件。
+
+### Task 2: 实现统一环境模板
+
+**Files:**
+- Create: `deploy/env/development/api.env.example`
+- Create: `deploy/env/development/scheduler.env.example`
+- Create: `deploy/env/development/worker.env.example`
+- Create: `deploy/env/development/web.env.example`
+- Create: `deploy/env/production/api.env.example`
+- Create: `deploy/env/production/scheduler.env.example`
+- Create: `deploy/env/production/worker.env.example`
+- Create: `deploy/env/production/web.env.example`
+- Modify: `.gitignore`
+
+**Interfaces:**
+- Consumes: GOV-006 设计中的变量作用域。
+- Produces: 后续 NestJS Schema 和部署方式共同使用的变量名契约。
+
+- [ ] **Step 1: 编写四类进程模板**
+
+每项变量附中文说明；敏感变量保持空值；MySQL/RabbitMQ/AI 由功能开关控制条件必填；生产值拒绝模拟数据和调试模式。
+
+- [ ] **Step 2: 加固忽略规则**
+
+只允许提交 `*.env.example`，忽略 `*.env.local`、真实 env 和本地运行目录。
+
+### Task 3: 实现本地 Redis 与生产部署骨架
+
+**Files:**
+- Create: `deploy/compose/development.yml`
+- Create: `deploy/compose/production.yml.example`
+- Create: `deploy/systemd/a-share-api.service.example`
+- Create: `deploy/systemd/a-share-scheduler.service.example`
+- Create: `deploy/systemd/a-share-worker.service.example`
+- Create: `deploy/nginx/a-share-analysis.conf.example`
+- Create: `docs/deployment/local-development.md`
+- Create: `docs/deployment/docker-compose-production.md`
+- Create: `docs/deployment/ubuntu-source-production.md`
+
+**Interfaces:**
+- Consumes: Task 2 的模板键集合。
+- Produces: 本地 Redis 启动入口、生产 Compose 配置边界、systemd EnvironmentFile 和 Nginx 代理示例。
+
+- [ ] **Step 1: 配置本地 Redis Compose**
+
+固定 Redis 镜像补丁版本，只暴露本机端口，使用项目专用容器名、网络、健康检查和仓库外本地数据目录；不得定义其他服务。
+
+- [ ] **Step 2: 配置生产部署骨架**
+
+生产 Compose 只表达应用服务的配置契约和不可变镜像要求；systemd 使用独立 EnvironmentFile，Nginx 托管静态文件并代理 `/api/`。
+
+- [ ] **Step 3: 编写开发与双生产部署文档**
+
+明确当前应用尚未脚手架化，文档只验证配置与部署边界；列出管理员前置条件、版本检查、健康检查、升级和回退规则。
+
+- [ ] **Step 4: 验证测试转绿**
+
+运行：`npm run test:environment-baseline && npm run test:mysql-baseline && npm run test:governance`
+
+预期：全部通过。Docker 可用时额外运行 `docker compose -f deploy/compose/development.yml config`。
+
+### Task 4: 完成现行规范、追溯与发布
+
+**Files:**
+- Modify: `docs/architecture/system-architecture.md`
+- Modify: `docs/governance/code-development-standards.md`
+- Modify: `docs/governance/development-workflow.md`
+- Modify: `README.md`
+- Modify: `docs/index.md`
+- Modify: `CHANGELOG.md`
+- Modify: `VERSION`
+- Create: GOV-006 除现有 `design.md`、`implementation-plan.md`、`gitnexus/before.md` 外的全部必备档案。
+
+**Interfaces:**
+- Consumes: 通过契约测试的配置与部署文件。
+- Produces: 可审查、可发布、可回退的 GOV-006 完整档案和 `v0.0.5`。
+
+- [ ] **Step 1: 更新架构和开发规范**
+
+记录环境模型、配置校验、两种部署方式、平台范围、管理员职责和生产防误用要求。
+
+- [ ] **Step 2: 执行 GitNexus、测试和双 Review**
+
+检测完整暂存区并运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。
+
+- [ ] **Step 3: 中文提交、推送与发布**
+
+提交并推送 `main`；封存后创建带注释 `v0.0.5`，精确推送并核对分支与标签。
@@ -0,0 +1,17 @@
+id: GOV-006
+name: 开发、生产环境与双部署方式
+slug: environment-deployment-baseline
+status: verifying
+owner: project
+created_at: 2026-08-13
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+gitnexus_before: gitnexus/before.md
+gitnexus_after: gitnexus/after.md
+gitnexus_comparison: gitnexus/comparison.md
+code_review: review/code-review.md
+standards_review: review/standards-review.md
+implementation_commit: pending
+release: v0.0.5
@@ -0,0 +1,31 @@
+# 开发、生产环境与双部署方式 PRD
+
+- 功能编号：GOV-006
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 问题
+
+项目缺少开发/生产配置契约和部署边界，存在真实配置入库、生产误用模拟数据及两种部署方式行为漂移的风险。
+
+## 目标
+
+- 提供开发和生产的四类进程无秘密模板。
+- 本地只用 Compose 启动 Redis，应用从源码运行。
+- 同时规范 Docker Compose 与 Ubuntu 源码生产部署。
+- 生产配置严格校验且不随发布版本覆盖。
+
+## 非目标
+
+- 不安装服务器运行时或基础设施。
+- 不声称尚未实现的应用镜像、进程和健康端点已经可运行。
+- 不启用 MySQL、RabbitMQ、正式数据源或 AI。
+
+## 验收标准
+
+- 八份模板完整、跨环境键一致且无敏感值。
+- Web 模板只含公开 `VITE_*` 变量。
+- 开发 Compose 仅定义 Redis并可通过配置解析。
+- systemd、Nginx 和三份部署文档满足已确认平台与路径边界。
+- 环境契约测试完成红绿验证，双 Review 和治理门禁通过。
@@ -0,0 +1,16 @@
+# 测试结果
+
+## 测试先行证据
+
+新增环境基线测试后首次运行 6 个测试全部失败，分别指出八份模板、开发 Compose、systemd/Nginx 示例和部署文档不存在。
+
+补齐最小实现后：
+
+- 环境基线测试：6 个通过，0 个失败。
+- MySQL 基线测试：2 个通过，0 个失败。
+- 治理测试：5 个通过，0 个失败。
+- `docker compose -f deploy/compose/development.yml config`：通过，仅包含 Redis。
+- `git diff --check`：通过。
+- GitNexus 最终暂存区：43 个文件、77 个符号、0 条流程，风险为低。
+
+生产 Compose 和源码部署当前属于配置契约骨架，应用尚未脚手架化，因此没有伪造生产启动或健康检查成功证据。
@@ -0,0 +1,3 @@
+# 视觉验证
+
+本功能没有页面或交互变化，视觉验证不适用。
@@ -0,0 +1,8 @@
+# 发布说明
+
+## v0.0.5
+
+- 新增八份开发/生产无秘密环境模板。
+- 新增只启动 Redis 的本地开发 Compose。
+- 新增生产 Compose 契约骨架、systemd/Nginx 示例和 Ubuntu 源码部署规范。
+- 新增环境配置自动化契约测试。
@@ -0,0 +1,10 @@
+# 工程需求
+
+- 环境只定义 `development` 与 `production`。
+- API、Scheduler、Worker、Web 分别提供开发/生产模板，同进程键集合一致。
+- 敏感变量保持空值，真实配置被 Git 忽略。
+- 生产 Worker 固定 `MARKET_DATA_MODE=live`，第一阶段关闭 MySQL 与 RabbitMQ。
+- 本地 Compose 固定 Redis 补丁版本、仅绑定本机并提供健康检查。
+- Ubuntu 源码部署支持 22.04/24.04 LTS x86_64、Node.js 22 LTS、pnpm 10。
+- systemd 使用 `a-share` 用户及独立 `EnvironmentFile`；Nginx 托管静态文件并代理 API。
+- 生产 Compose 使用不可变镜像和外部 env，不承诺当前骨架可直接上线。
@@ -0,0 +1,27 @@
+# 配置与文档 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 基线提交：`0328f9e`
+- 设计提交：`fa1df71`
+- 实现提交：`pending`
+- 日期：2026-08-13
+
+## 审查结论
+
+八份模板保持跨环境键一致，敏感值为空，Web 只含公开变量；开发 Compose 只启动 Redis；生产部署示例明确为未验证骨架。现行架构和规范覆盖启动校验、防误用与管理员职责。
+
+## 发现与处置
+
+| 严重程度 | 发现 | 处置 |
+|---|---|---|
+| Important | 两种部署方式可能形成不同变量协议 | 强制复用同一模板键并用自动测试比较 |
+| Important | 示例容易被误认为可直接上线 | Compose 和文档显式标记需在应用脚手架后验证 |
+| Important | 前端变量可能泄露服务端秘密 | 测试要求 Web 模板每个键都以 `VITE_` 开头且只含公开值 |
+| Minor | 本地 Redis 数据可能进入仓库 | 使用 `.local/redis` 并加固忽略规则 |
+
+- 环境契约测试 6/6、MySQL 基线 2/2、治理测试 5/5 通过。
+- Docker Compose 配置解析成功且只包含 Redis。
+- GitNexus 最终暂存区检测为 43 个文件、77 个符号、0 条流程、低风险。
+
+最终结论：passed
@@ -0,0 +1,21 @@
+# 开发规范符合性 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 实现提交：`pending`
+- 日期：2026-08-13
+
+## 检查结果
+
+- [x] 设计经用户确认后实施。
+- [x] 环境契约先有 6 个失败测试，再补实现使其通过。
+- [x] 模板无真实秘密，真实 env 与本地数据被忽略。
+- [x] 不连接或探测生产服务，不安装服务器软件。
+- [x] MySQL 变量符合 GOV-005，第一阶段默认关闭。
+- [x] Docker Compose 与源码部署共享变量契约。
+- [x] 未把尚未实现的应用描述为已可部署。
+- [x] 无界面变化，视觉验证合理标记不适用。
+
+没有未解决的 Critical 或 Important 不符合项。
+
+最终结论：passed
@@ -0,0 +1,5 @@
+# 回退说明
+
+本功能没有部署应用或连接生产服务。若配置规范需要修正，使用新的中文修复提交更新模板、文档和测试，不移动共享标签。
+
+开发 Redis 数据位于被忽略的 `.local/redis/`，版本回退不得自动删除该目录。生产真实 env 位于仓库外，不随应用版本切换覆盖。
@@ -0,0 +1,8 @@
+# 测试计划
+
+- 先运行环境基线测试，证明六类行为因模板和部署文件缺失而失败。
+- 实现后要求环境测试 6/6、MySQL 基线 2/2、治理测试 5/5 通过。
+- 运行 Docker Compose 配置解析，确认只有 Redis。
+- 运行 `git diff --check`、敏感信息扫描和 GitNexus 最终暂存区检测。
+- 运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。
+- 本功能无页面变化，视觉验证不适用。
@@ -82,7 +82,18 @@ count += 1;
 - 免费数据源失败时保留最后有效快照，并明确标记陈旧，禁止伪装实时数据。
 - AI 失败不得影响规则分析和基础行情展示。

-## 8. 前端规范
+## 8. 环境配置规范
+
+- 应用只接受 `development` 与 `production`，环境必须显式设置。生产启动不得回退到开发默认值、模拟数据、热更新或调试模式。
+- API、Scheduler、Worker 必须使用各自的配置 Schema，在进程启动时验证类型、格式、范围和条件必填项；配置错误立即退出。
+- 同一进程的开发与生产模板必须保持相同变量名。环境差异通过配置值、依赖注入和 Adapter 收敛，禁止在业务代码中散落 `APP_ENV` 分支。
+- 只有 `*.env.example` 可以提交；真实 `.env`、`*.env.local`、密码、Token 和 API Key 必须被 Git 忽略并由运行环境注入。
+- Web 只能使用公开的 `VITE_*` 变量。数据库、Redis、RabbitMQ、数据源和 AI 凭据禁止进入前端变量或构建产物。
+- MySQL、RabbitMQ、正式数据源与 AI 使用显式功能开关；关闭时连接变量可为空，开启后缺少任何必填值都必须拒绝启动。
+- Docker Compose 与源码部署必须复用同一变量契约，禁止为某种部署方式建立语义不同的别名。
+- 生产配置必须位于发布目录之外，切换应用版本不得覆盖配置；日志和诊断输出必须对配置值脱敏。
+
+## 9. 前端规范

 - 页面不得直接访问第三方行情源、Redis、RabbitMQ 或 AI 服务。
 - 全局服务器状态使用 TanStack Vue Query，本地界面偏好使用 Pinia或轻量组合式函数。
@@ -91,14 +102,14 @@ count += 1;
 - 图表必须标注单位、时间范围、数据日期和更新时间。
 - 所有核心交互覆盖加载、空、部分数据、错误和过期状态。

-## 9. 后端与任务规范
+## 10. 后端与任务规范

 - API、Scheduler和Worker作为独立进程维护，不在请求期间临时抓取全市场数据。
 - Scheduler只决定何时投递；RabbitMQ负责任务传输；Worker负责执行；MySQL负责事实记录；Redis负责当前快照和短期状态。
 - 消费者必须幂等，消息确认只能发生在持久化或可验证处理完成后。
 - 免费数据源通过 Adapter 统一为内部模型，上层不得依赖供应商原始字段。

-## 10. MySQL 5.7 兼容规范
+## 11. MySQL 5.7 兼容规范

 - 开发、测试、Docker 和生产环境必须使用明确的 MySQL 5.7 补丁版本，禁止使用 `latest`、MySQL 8.x 或其他数据库代替兼容性验证。
 - 创建数据库必须显式声明 `DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci`；建表与迁移脚本必须显式保持 `DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci`。
@@ -112,7 +123,7 @@ count += 1;
 - 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7 正向执行；禁止用直接修改共享数据库表代替迁移脚本。
 - 代码 Review 必须检查服务端版本、字符集、排序规则、SQL/迁移兼容性、索引长度和字符串比较语义；任一不符合项按 Important 处理并阻断发布。

-## 11. 测试要求
+## 12. 测试要求

 - 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
 - 纯规则和指标计算使用单元测试，期望值必须手工推导。
@@ -121,14 +132,14 @@ count += 1;
 - 关键页面使用 Playwright流程测试和视觉截图对比。
 - 合并前必须通过类型检查、测试、构建和适用的视觉验证。

-## 12. 安全要求
+## 13. 安全要求

 - 禁止提交 `.env`、API Key、密码、真实账号和生产数据。
 - AI 密钥、数据源凭证和支付凭证仅存在服务端密钥管理中。
 - SQL必须参数化；外部输入必须在边界处校验。
 - 日志和异常报告必须脱敏。

-## 13. 代码 Review 要求
+## 14. 代码 Review 要求

 开发者完成自测不等于 Review 完成。审查者必须从功能 PRD、设计和 Git diff 出发，检查：

@@ -23,14 +23,15 @@ released → superseded
 5. 比较可选方案，记录设计与关键决策。
 6. 更新 API、事件和数据结构契约。
 7. 编写测试计划和实施计划。
-8. 确保 Git 工作区基线可识别，执行：
+8. 明确功能需要的环境变量、功能开关和部署影响；同步更新开发/生产模板，禁止只修改本机真实 env。
+9. 确保 Git 工作区基线可识别，执行：

 ```bash
 npm run governance:start -- FEAT-MO-001 market-overview
 ```

-9. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
-10. 高风险或关键路径变化必须先向用户说明影响，再进入开发。
+10. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
+11. 高风险或关键路径变化必须先向用户说明影响，再进入开发。

 开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。

@@ -79,6 +80,7 @@ npm run governance:finish -- FEAT-MO-001 market-overview
 - 发布说明和回退方法可执行。
 - 中文提交已关联功能编号。
 - 当前分支和本次新建标签已推送到 `origin`，功能档案保存远程核对结果。
+- 配置契约变化已同步开发/生产模板和适用的 Compose、systemd、Nginx及部署文档。

 ## 7. 提交流程

@@ -15,6 +15,12 @@
 - [ADR-0001：单仓库双项目独立部署](adr/ADR-0001-monorepo-independent-deploy.md)
 - [ADR-0002：GitNexus 双门禁](adr/ADR-0002-gitnexus-double-gate.md)

+## 环境与部署
+
+- [本地开发环境](deployment/local-development.md)
+- [Docker Compose 生产部署](deployment/docker-compose-production.md)
+- [Ubuntu 源码生产部署](deployment/ubuntu-source-production.md)
+
 ## GitNexus

 - [仓库基线](gitnexus/repository-baseline.md)
@@ -29,5 +35,6 @@
 - [GOV-003：项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml)
 - [GOV-004：提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml)
 - [GOV-005：MySQL 5.7 字符集与兼容性基线](features/GOV-005-mysql57-charset-baseline/manifest.yaml)
+- [GOV-006：开发、生产环境与双部署方式](features/GOV-006-environment-deployment-baseline/manifest.yaml)

 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。