# 本地开发环境

本地开发由开发机提供 Node.js 22.x、pnpm 10.25.0 和已开机自启的 Redis `127.0.0.1:6379`。Web、API、Scheduler 与 Worker 全部从源码启动；MySQL 5.7.x 和 RocketMQ 5.x 也是外部服务，项目脚本不负责安装、启动、停止或删除任何基础设施。

## 首次准备

```bash
node --version
pnpm --version
redis-cli -h 127.0.0.1 -p 6379 ping
pnpm install --frozen-lockfile
pnpm check:runtime
```

Redis 必须返回 `PONG`。如果不可达，应先修复开发机外部服务；测试和应用不会创建替代实例。

把 `deploy/env/development/*.env.example` 复制为同目录的 `*.env.local`。四份 local 文件被 Git 忽略：Web 只能含 `VITE_` 公开变量；API、Scheduler、Worker 按最小权限分别读取自己的配置，不共享一份全能 env。

固定开发 MySQL 只允许 `a_share_analysis_dev`，主机必须是回环地址或代码内白名单 `112.192.20.11`，服务端必须属于 MySQL 5.7.x 且不限制系列内补丁版本，字符集为 `utf8mb4`、排序规则为 `utf8mb4_general_ci`、会话时区为 `+08:00`。Schema 工具和开发检查禁止连接、探测或读取生产库。

## 启动顺序

建议分别打开四个终端，依次运行：

```bash
pnpm --filter @a-share-analysis/server dev:api
pnpm --filter @a-share-analysis/server dev:scheduler
pnpm --filter @a-share-analysis/server dev:worker
pnpm --filter @a-share-analysis/web dev
```

API 健康端点是 `http://127.0.0.1:3000/api/v1/health`，Web 是 `http://127.0.0.1:8888/`。Scheduler 与 Worker 在 GOV-009 中保持 `ROCKETMQ_ENABLED=false`；没有经过验证的 Node RocketMQ 客户端时，启用配置会直接失败，不使用内存队列伪降级。

## AKTools 补充数据源

AKTools/AKShare 作为开发机外部服务单独运行，默认地址为 `http://127.0.0.1:8080`。启动 API 前确认服务可访问；需要启用短线情绪模块时，在 API local 配置中设置 `AKTOOLS_ENABLED=true`，否则模块明确显示不可用，不影响 TDX 模块。Nest 只允许三个已验证接口，前端不直连 AKTools。项目不会管理该 Python 服务的安装、进程和数据。

```bash
curl --fail 'http://127.0.0.1:8080/api/public/stock_zt_pool_em?date=20260824'
```

生产环境不能直接复用本机 AKTools 配置；启用前必须提供受控内网地址、认证/访问控制、上游授权和稳定性评估，并扩展服务端白名单校验。

## 日常验证与停止

```bash
pnpm check:contracts
pnpm verify
pnpm verify:release
```

应用进程通过各自终端或信号正常停止，外部 Redis/MySQL/RocketMQ 生命周期不由项目管理。RocketMQ 的 TCP 端口可达不等于生产消费链路通过，完整联调仍需验证 Topic 路由和实际生产/消费。