docs(GOV-006): 明确环境与双部署方式设计

docs/features/GOV-006-environment-deployment-baseline/design.md

@@ -0,0 +1,177 @@
+# 开发、生产环境与双部署方式设计规格
+
+- 功能编号：GOV-006
+- 规格版本：0.1
+- 状态：approved_for_review
+- 日期：2026-08-13
+
+## 背景与目标
+
+项目已经明确前后端和基础设施技术栈，但目前只有 `.gitignore` 排除 `.env`，没有正式的开发/生产配置契约、模板结构、加载优先级和部署边界。缺少这些规则会导致本地开发误用生产配置、生产回退到模拟数据、不同部署方式使用不同变量，以及密钥进入仓库或构建产物。
+
+本功能建立统一的环境配置体系，并同时支持 Docker Compose 与 Ubuntu 源码生产部署。两种生产方式必须使用相同变量名、配置校验、进程边界和发布版本，不允许形成两套行为不同的应用。
+
+## 环境模型
+
+项目只定义两个应用运行环境：
+
+- `development`：本地开发、热更新、确定性模拟数据和开发 Redis。
+- `production`：线上运行，禁止热更新、调试端口、模拟数据和开发默认值回退。
+
+测试运行使用测试工具自己的隔离配置，不把 `test` 作为可部署环境。应用启动必须显式获得环境值；生产环境缺少配置或出现非法组合时立即退出，不能静默使用开发默认值。
+
+业务代码不得到处分支判断环境。环境差异在配置加载、依赖注入和基础设施 Adapter 边界收敛，纯业务计算保持一致。
+
+## 仓库模板结构
+
+仓库提交完整但不含秘密的模板：
+
+```text
+deploy/env/
+├── development/
+│   ├── api.env.example
+│   ├── scheduler.env.example
+│   ├── worker.env.example
+│   └── web.env.example
+└── production/
+    ├── api.env.example
+    ├── scheduler.env.example
+    ├── worker.env.example
+    └── web.env.example
+```
+
+每个模板必须为每项变量写明用途、示例格式、是否必填、敏感性和启用条件。密码、Token 和 API Key 使用空值，不使用看似真实的占位凭据。
+
+真实开发配置使用同目录或项目约定位置的 `*.env.local`，由 Git 忽略。真实生产配置永远不放在仓库、发布目录、镜像层或前端构建产物中。
+
+## 配置契约与校验
+
+API、Scheduler、Worker 使用独立 Schema 校验各自配置，遵守最小知情范围：
+
+- API：HTTP 监听、Redis、当前快照、按需历史读取和 AI 调用配置。
+- Scheduler：时区、交易日调度、Redis 分布式锁；RabbitMQ 未启用时使用服务内调度 Adapter。
+- Worker：数据源、Redis、分析配置；未来启用时增加 MySQL、RabbitMQ 和 AI 变量。
+- Web：只允许公开的 `VITE_*` 构建变量，例如 API 相对路径和应用标题。
+
+功能开关控制条件必填：MySQL、RabbitMQ、正式数据源或 AI 未启用时，其连接变量可以为空；一旦开关启用，相关变量缺失、格式错误或不安全时必须拒绝启动。
+
+前端构建环境变量会进入浏览器代码，任何数据库、Redis、RabbitMQ、数据源或 AI 凭据都不得使用 `VITE_*` 前缀。
+
+## 本地开发方式
+
+本地开发默认使用 Docker Compose 只启动 Redis。Web、API、Scheduler 和 Worker 直接从源码运行，使用热更新和开发配置，便于调试。
+
+第一阶段不启动 MySQL 和 RabbitMQ：
+
+- MySQL 只定义 Repository 接口并使用内存实现。
+- RabbitMQ 只定义消息契约和发布接口，Scheduler 通过服务内 Adapter 调用任务。
+- Redis 是第一阶段唯一实际启用的外部基础设施，用于当前快照、缓存、刷新锁和调度锁。
+
+开发 Compose 文件不得加载生产配置，不得连接生产地址。开发服务名、网络和数据目录必须使用项目专用前缀，避免影响其他项目。
+
+## Docker Compose 生产部署
+
+生产 Compose 支持运行 Web/Nginx、API、Scheduler、Worker，以及按部署选择连接内部或外部 Redis、MySQL 5.7 和 RabbitMQ。第一阶段未启用的组件不应为了形式完整而启动。
+
+要求：
+
+- 镜像对应明确 Git 提交或版本标签，禁止使用浮动 `latest` 作为可回退版本。
+- 使用外部指定的生产 env 文件加载同一配置契约，不把秘密写入 Compose YAML。
+- 禁止源码挂载、热更新、调试端口和开发命令。
+- 服务提供健康检查、日志边界、启动顺序和优雅停止。
+- 数据目录使用明确宿主机路径或经确认的持久化方案，升级不得删除数据。
+
+## Ubuntu 源码生产部署
+
+正式支持平台：
+
+- Ubuntu 22.04 LTS x86_64。
+- Ubuntu 24.04 LTS x86_64。
+
+服务器管理员预先提供并维护：
+
+- Node.js 22 LTS。
+- pnpm 10。
+- Nginx。
+- MySQL 5.7、Redis、RabbitMQ 或对应外部服务。
+
+项目只验证版本和连通性，不修改软件源，不安装或升级 Node.js、pnpm、Nginx、MySQL、Redis 或 RabbitMQ。版本不符合要求时部署立即终止并给出明确错误。
+
+依赖安装必须使用 `pnpm install --frozen-lockfile`。Web 构建为静态文件后由 Nginx 托管；API、Scheduler 和 Worker 运行编译后的 JavaScript，禁止在生产运行 TypeScript、Vite 开发服务器、Nest watch 或源码热更新。
+
+## systemd 与生产配置位置
+
+源码部署使用单个非登录系统用户 `a-share` 运行 API、Scheduler 和 Worker。第一阶段先降低部署复杂度，但仍把配置拆为独立文件，为以后按进程拆系统用户保留边界。
+
+生产配置固定存放在发布目录之外：
+
+```text
+/etc/a-share-analysis/
+├── api.env
+├── scheduler.env
+├── worker.env
+└── web.env
+```
+
+systemd 单元通过 `EnvironmentFile=/etc/a-share-analysis/<进程>.env` 在启动时注入变量。切换 `/opt/a-share-analysis/current` 指向的应用版本不会覆盖配置。
+
+API、Scheduler 和 Worker 分别只引用自己的 env 文件。第一阶段文件所有者为 `root:a-share`，包含秘密的文件权限为 `0640`；Web 配置只含公开构建变量，可由部署构建步骤读取。未来接入高价值数据源和 AI 密钥时，评估拆分独立系统用户和更细的文件组权限。
+
+## 发布目录与进程边界
+
+源码部署建议使用不可变版本目录：
+
+```text
+/opt/a-share-analysis/
+├── releases/<版本或提交>/
+└── current -> releases/<当前版本>/
+```
+
+更新时先在新目录安装、构建和校验，再原子切换 `current` 并重启服务。回退切回上一完整版本，不在旧目录上覆盖文件。
+
+Nginx 托管当前版本 Web 静态产物并反向代理 API。API、Scheduler、Worker 为独立 systemd 服务；任一后台进程异常不得由 API 请求临时替代执行全市场采集任务。
+
+## MySQL 兼容约束
+
+两种部署方式和两个环境都受 GOV-005 约束：MySQL 固定 5.7.x，字符集 `utf8mb4`，排序规则 `utf8mb4_general_ci`。项目启动或迁移必须验证该条件，不得在开发环境使用 8.x 再假设向下兼容。
+
+第一阶段 MySQL 未启用，因此配置模板保留功能开关和条件变量，但默认不连接数据库。
+
+## 安全与防误用
+
+- `.env`、`.env.*` 和 `*.env.local` 默认忽略，只允许提交 `*.env.example`。
+- 模板、日志、错误和诊断输出不得包含真实秘密。
+- 生产启动必须检查 `APP_ENV=production`，并拒绝模拟数据、开发 URL、调试模式和空的已启用服务凭据。
+- 开发配置不得包含或连接生产主机；项目脚本禁止读取生产数据库进行开发验证。
+- Docker Compose 与源码部署使用相同变量名称和 Schema，不用环境专属别名隐藏差异。
+- Web 配置仅含公开值；所有付费 AI 和数据源密钥只存在服务端配置。
+
+## 运维文档范围
+
+两种生产部署方式都必须提供：
+
+- 前置条件和版本检查。
+- 初次部署、配置填充、构建和启动步骤。
+- 健康检查、日志读取和进程状态检查。
+- 使用确定版本的升级流程。
+- 配置不变的应用回退流程。
+- 数据服务备份职责声明和故障边界。
+
+源码部署文档不提供基础设施安装脚本。Docker Compose 文档不能暗示其配置可以直接用于本地开发。
+
+## 实施范围
+
+GOV-006 建立环境规范、变量模板、开发 Redis Compose、生产部署骨架、systemd/Nginx 示例及验证脚本的设计与追溯基础。由于 Web、Server、Scheduler 和 Worker 尚未实现，当前可先提供结构完整的模板和部署规范；具体应用启动命令在相应项目脚手架落地后通过后续功能验证，不得伪造已可运行状态。
+
+## 验收标准
+
+- 仓库包含开发与生产环境下 API、Scheduler、Worker、Web 的八份无秘密模板。
+- 本地开发仅通过 Compose 启动项目专用 Redis，应用从源码运行。
+- 生产同时有 Docker Compose 和 Ubuntu 22.04/24.04 x86_64 源码部署规范。
+- 源码部署明确管理员提供 Node.js 22 LTS、pnpm 10、Nginx 和基础设施，项目只验证不安装。
+- 源码部署明确单个 `a-share` 用户、独立 EnvironmentFile 和发布目录边界。
+- Docker Compose 与源码部署共用配置变量和校验规则。
+- 生产环境无法回退到模拟数据、开发默认值、热更新或调试配置。
+- MySQL 条件配置符合 GOV-005，第一阶段默认不启用 MySQL 和 RabbitMQ。
+- 治理测试、模板静态检查、敏感信息检查、GitNexus 变更检测和双 Review 通过。
+- 中文提交和对应版本标签精确推送到 Gitea。

docs/features/GOV-006-environment-deployment-baseline/gitnexus/before.md

@@ -0,0 +1,26 @@
+# GitNexus 开发前基线
+
+- 功能编号：GOV-006
+- 记录时间：2026年8月13日 GMT+8 10:34:15
+- 分支：main
+- 基线提交：0328f9e3d27d
+
+## 工作区
+
+```text
+M AGENTS.md
+```
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/13/2026, 10:34:14 AM
+Indexed commit: 0328f9e
+Current commit: 0328f9e
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。