docs(FEAT-MO-003): 更新项目 README

README.md

@@ -1,26 +1,56 @@
 # A-Share Analysis
 
-A read-only A-share market overview and analysis tool.
+一个只读的 A 股市场概览与盘面分析工具，面向个人复盘和小范围使用，不提供交易下单、荐股、社区或公开组合功能。
 
 ## 当前阶段
 
-项目正在建立工程基线，首个业务模块为市场综合概览。当前不包含用户体系、订阅与支付。
+项目当前以市场综合概览为首个业务模块，用户体系、订阅与支付暂不进入首屏业务范围。
+
+当前已接入 TDX 只读行情并完成以下首屏模块：
+
+- 市场结论、驱动因素和风险摘要。
+- 核心指数、三市场宽度、一级行业板块强弱和三市场成交额趋势。
+- 综合、短线、中长线视角入口，以及规则、AI、混合、对照分析偏好入口。
+- 指数和板块详情入口已预留，详情页另立功能实现；强势个股模块尚未开发。
+
+主力净流入、完整盘中新闻、版本化概念题材成分和 AI 自动结论仍需独立数据源或后续功能立项，不用 TDX 缺失字段冒充。
 
 ## Projects
 
-- `web/`: Vue 3 market terminal frontend.
-- `server/`: NestJS API、Scheduler 与 Worker 三个独立进程。
-- `deploy/`: MySQL 5.7、Redis、RocketMQ 5.x 的配置契约，以及 systemd/Nginx 源码部署模板。
-- `docs/`: Product and implementation specifications.
+- 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、契约、边界和治理验证工具。
 
-The first implementation slice is the market overview screen in `web/`.
+首个实现切片是 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.25.0、Nginx 和外部基础设施由服务器管理员提供。项目不安装、启动、停止或删除 Redis、MySQL 和 RocketMQ。
+无秘密环境模板位于 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 配置和具体功能需求为准。
+
+数据库开发约束：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。
 
 ## 开发入口
 
@@ -28,6 +58,9 @@ The first implementation slice is the market overview screen in `web/`.
 - [代码开发规范](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`，然后运行：
 
@@ -39,6 +72,23 @@ 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>