a-share-analysis/README.md

A-Share Analysis

一个只读的 A 股市场概览与盘面分析工具，面向个人复盘和小范围使用，不提供交易下单、荐股、社区或公开组合功能。

当前阶段

项目当前以市场综合概览为首个业务模块，用户体系、订阅与支付暂不进入首屏业务范围。

当前已接入 TDX 只读行情并完成以下首屏模块：

• 市场结论、驱动因素和风险摘要。
• 核心指数、三市场宽度、一级行业板块强弱和三市场成交额趋势。
• 综合、短线、中长线视角入口，以及规则、AI、混合、对照分析偏好入口。
• 指数和板块详情入口已预留，详情页另立功能实现；强势个股模块尚未开发。
• 超短情绪补充模块已接入本机 AKTools：展示涨停、最高连板、炸板、昨日涨停表现、涨停行业和规则结论；AKTools 不可用时独立降级。

主力净流入、完整盘中新闻、版本化概念题材成分和 AI 自动结论仍需独立数据源或后续功能立项，不用 TDX 或 AKShare 缺失字段冒充。

Projects

• web/: Vue 3、Vite、TypeScript、Naive UI、Dart Sass、Axios 前端。
• server/: NestJS API、Scheduler 与 Worker 三个独立源码进程。
• deploy/: MySQL 5.7.x、Redis、RocketMQ 5.x 的配置契约，以及 systemd/Nginx 源码部署模板。
• docs/: PRD、架构、治理、部署和功能档案。
• tools/: Schema、契约、边界和治理验证工具。

首个实现切片是 web/ 下的市场综合概览首屏。

环境与部署

• 本地开发环境：使用开发机已有 Redis，应用全部从源码运行。
• Ubuntu 源码生产部署：项目唯一生产部署方式，支持 Ubuntu 22.04/24.04 LTS x86_64。

无秘密环境模板位于 deploy/env/。生产配置不进入 Git 或发布目录；Node.js 22.x、pnpm 10.x、Nginx 和外部基础设施由服务器管理员提供。项目不安装、启动、停止或删除 Redis、MySQL 和 RocketMQ。

前端开发服务器固定监听 127.0.0.1:8888，API 使用 127.0.0.1:3000。当前首屏不依赖 Scheduler、Worker 或 RocketMQ 消费链路；MySQL、Redis 和 RocketMQ 是否启用，以各进程的 local 配置和具体功能需求为准。

AKTools 是项目外部维护的 AKShare HTTP 服务，开发机默认监听 127.0.0.1:8080。API 仅在 AKTOOLS_ENABLED=true 时调用三个固定接口；项目不安装、启动、停止或暴露 AKTools，也不允许前端直接请求它。生产是否启用必须先完成上游授权、稳定性和访问控制评估。

数据库开发约束：Schema 基线只能读取开发库 a_share_analysis_dev，禁止触碰生产库；字符集为 utf8mb4，排序规则为 utf8mb4_general_ci，时区为东八区。

TDX 连接方式

平台始终访问 Mac 本机回环地址 http://127.0.0.1:17710/。该地址由 SSH 隧道转发到家中 Windows 的 TDX 客户端 127.0.0.1:17709，不把 TDX 暴露到局域网或公网。

在家使用 tdx-windows-lan，在外通过 Tailscale 使用 tdx-windows-tailnet；两种隧道不能同时启动：

# 外部网络场景
tailscale up
tailscale ping <WINDOWS_TAILSCALE_HOST>
ssh -fN -M -S ~/.ssh/tdx-windows-tailnet-control tdx-windows-tailnet

nc -vz 127.0.0.1 17710
lsof -nP -iTCP:17710 -sTCP:LISTEN

完整的 Windows OpenSSH、双场景切换、停止和只读冒烟步骤见 docs/deployment/tailscale-tdx-development.md。

开发入口

• 文档索引
• 代码开发规范
• 开发流程规范
• 系统架构
• 本地开发环境
• TDX 隧道开发手册
• Ubuntu 源码生产部署

开始任何模块前，先阅读根目录 AGENTS.md，然后运行：

npm run schema:baseline
npm run schema:verify
npm run governance:start -- FEAT-MO-001 market-overview

Schema 命令只允许处理固定开发库；导出器使用 Node.js mysql2，本机无需安装 MySQL Server 或 CLI。当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单，不会连接数据库或创建空 SQL；启用但无对象时生成 format v3 captured_empty 清单。完整规则见 开发流程规范。

本地启动

pnpm install --frozen-lockfile
pnpm check:runtime
redis-cli -h 127.0.0.1 -p 6379 ping
pnpm --filter @a-share-analysis/server dev:api
pnpm --filter @a-share-analysis/web dev

访问 Web：http://127.0.0.1:8888/；访问 API 健康检查：http://127.0.0.1:3000/api/v1/health。前端同源 /api 请求由 Vite 代理到 API，strictPort 已启用，8888 被占用时会明确失败，不会静默换端口。

Scheduler 和 Worker 只在对应任务链路开发时启动：

pnpm --filter @a-share-analysis/server dev:scheduler
pnpm --filter @a-share-analysis/server dev:worker

前端 API 请求统一经过 web/src/utils/request.ts 封装的 Axios；业务请求位于 web/src/api/<业务域>/index.ts。

项目仓库

• Gitea：https://git.foximao.com/FoXiMao/a-share-analysis
• 远程名：origin
• 配置范围：仅当前项目的 .git/config，不修改 Git 全局配置。

凭据不写入仓库、文档或远程 URL。首次需要认证时由 Git 调用 macOS Keychain 安全保存；详细规则见 Git 与 Gitea 规范。

验证通过的中文提交必须立即同步当前分支到 Gitea；本次创建的版本标签单独同步。远程同步失败时，开发任务保持未完成状态。