a-share-analysis/docs/features/GOV-006-environment-deployment-baseline/implementation-plan.md

开发、生产环境与双部署方式实施计划

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，精确推送并核对分支与标签。