105 lines
5.7 KiB
Markdown
105 lines
5.7 KiB
Markdown
# 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/ 下的市场综合概览首屏。
|
||
|
||
## 环境与部署
|
||
|
||
- [本地开发环境](docs/deployment/local-development.md)：使用开发机已有 Redis，应用全部从源码运行。
|
||
- [Ubuntu 源码生产部署](docs/deployment/ubuntu-source-production.md)：项目唯一生产部署方式，支持 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。
|
||
|
||
## 开发入口
|
||
|
||
- [文档索引](docs/index.md)
|
||
- [代码开发规范](docs/governance/code-development-standards.md)
|
||
- [开发流程规范](docs/governance/development-workflow.md)
|
||
- [系统架构](docs/architecture/system-architecture.md)
|
||
- [本地开发环境](docs/deployment/local-development.md)
|
||
- [TDX 隧道开发手册](docs/deployment/tailscale-tdx-development.md)
|
||
- [Ubuntu 源码生产部署](docs/deployment/ubuntu-source-production.md)
|
||
|
||
开始任何模块前，先阅读根目录 `AGENTS.md`，然后运行：
|
||
|
||
```bash
|
||
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` 清单。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。
|
||
|
||
### 本地启动
|
||
|
||
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 规范](docs/governance/version-control-and-gitea.md)。
|
||
|
||
验证通过的中文提交必须立即同步当前分支到 Gitea；本次创建的版本标签单独同步。远程同步失败时，开发任务保持未完成状态。
|