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

2026-08-24 17:51:31 +08:00
parent ab0b53a56b
commit 6cbfd8d8a4
19 changed files with 392 additions and 8 deletions
@@ -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>
@@ -0,0 +1,17 @@
+# 设计
+
+## 设计方案
+
+只修改根目录 README，事实来源固定为现有部署手册、系统架构、FEAT-MO-001 市场概览和 FEAT-MO-002 端口档案。README 作为入口索引，不复制完整的 Tailscale、生产部署或治理规则。
+
+## 安全策略与评估
+
+仅写入 TDX 本机回环入口、SSH 别名和占位符；不写真实 Windows 地址、Tailscale IP、SSH 用户、Token、密码或私钥。README 明确 TDX 不开放公网、Schema 禁止触碰生产库。
+
+## 性能目标与评估
+
+文档变化不影响编译、运行时和网络性能；只增加可发现性和启动指导。
+
+## 兼容与回退
+
+README 可以独立回退，不需要数据迁移或服务重启。后续端口、部署或数据源变更必须同步 README 和专项文档。
@@ -0,0 +1,39 @@
+# README 文档同步开发总结
+
+- 功能编号：FEAT-MO-003
+- 总结版本：0.1
+- 日期：2026-08-19
+
+## 原始开发需求
+
+用户指出 README 落后，要求更新为当前项目状态。
+
+## 需求与范围变化
+
+从旧的英文工程简介扩展为当前可运行状态说明，新增 8888 Web、TDX 双隧道、首屏模块、基础设施边界和启动验证；未改变代码和运行行为。
+
+## 实际完成需求
+
+- README 已同步当前市场概览首屏、技术栈和源码部署边界。
+- README 已同步 Web 8888、API 3000 和 TDX 17710 回环入口。
+- README 已补充 LAN/Tailscale 隧道、启动、停止和验证入口。
+- README 已补充 Schema、GitNexus、Review 和 Gitea 约束链接。
+
+## 修复缺陷
+
+修复 README 将项目描述、端口、启动方式和基础设施启用边界写旧的问题；没有业务代码缺陷修复。
+
+## 未完成与延期项
+
+README 不替代完整 Tailscale、生产部署和治理文档；这些内容继续由专项文档维护。
+
+## 关键提交
+
+尚未提交；等待 Review 和用户后续提交安排。
+
+## 验证证据
+
+- Schema：npm run schema:baseline 和 npm run schema:verify 通过，v0.0.10 captured_empty。
+- GitNexus：README upstream 风险 LOW，执行流 0；开发后检测已记录。
+- 文档检查：旧的当前端口引用清理，README 链接和命令与现有文件一致。
+- 安全：未写入凭据、真实 Tailscale 地址、Windows 用户或 Token。
@@ -0,0 +1,5 @@
+# GitNexus 开发后基线
+
+GitNexus 已刷新：3,122 nodes、4,343 edges、68 clusters、85 flows，状态 up-to-date。
+
+README upstream 风险 LOW，受影响执行流 0；开发后变更检测 risk_level=low、affected_count=0。
@@ -0,0 +1,32 @@
+# GitNexus 开发前基线
+
+- 功能编号：FEAT-MO-003
+- 记录时间：2026年8月19日 GMT+8 12:57:47
+- 分支：main
+- 基线提交：1f6ed00e6fbb
+
+## 工作区
+
+```text
+M AGENTS.md
+ M README.md
+ M docs/deployment/local-development.md
+ M web/playwright.config.ts
+ M web/src/vite-config.test.ts
+ M web/vite.config.ts
+?? docs/features/FEAT-MO-002-web-port-8888/
+```
+
+## GitNexus 状态
+
+```text
+Repository: <project-root>
+Indexed: 8/19/2026, 12:57:47 PM
+Indexed commit: 1f6ed00
+Current commit: 1f6ed00
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
@@ -0,0 +1,3 @@
+# GitNexus 前后对比
+
+开发前 README 使用旧的英文项目简介、5173 端口和不完整启动说明；开发后同步当前 8888、TDX 双隧道、首屏模块和治理入口。README 不参与业务执行流。
@@ -0,0 +1,5 @@
+# GitNexus 变更检测
+
+执行 `gitnexus_detect_changes({scope: "unstaged", repo: "a-share-analysis"})` 结果：changed_count=10、changed_files=6、affected_count=0、risk_level=low、受影响执行流 0。
+
+GitNexus 识别到 README 的 6 个章节和既有 AGENTS.md/本地开发文档章节；本功能没有业务代码或运行时执行流变化。AGENTS.md 的既有用户修改保留，不属于本功能。
@@ -0,0 +1,27 @@
+# GitNexus 开发前影响计划
+
+- 功能编号：FEAT-MO-003
+- 目标：同步根目录 README 与当前前端端口、TDX 双隧道、本地启动、技术栈和首屏能力。
+- 总体风险：LOW
+
+## 直接与间接影响
+
+- GitNexus context：README.md 仅关联 docs/index、治理、部署和架构文档，没有业务执行流调用方。
+- GitNexus impact：README.md upstream 直接调用方 0、受影响执行流 0、受影响模块 0，风险 LOW。
+- README 的事实来源为现有本地开发、TDX 隧道、系统架构和 FEAT-MO-001/002 功能档案。
+
+## 跨模块同步修改
+
+| 维度 | 判断 | 同步修改 |
+|---|---|---|
+| HTTP/OpenAPI | 不涉及 | 无 |
+| Web API | 不涉及 | 无 |
+| 消息、数据库、Redis | 不涉及运行配置 | 无 |
+| API、Scheduler、Worker | 不改变启动行为 | README 仅说明边界 |
+| 部署 | 仅补充现有源码部署和本地文档入口 | README 链接同步 |
+| 测试 | 文档变更不要求业务测试；执行格式检查和功能门禁 | 功能档案 |
+| 安全 | 不写入凭据、真实地址或 Token；保留回环和 TDX 隧道边界 | README |
+
+## 性能与残余风险
+
+README 不参与运行时路径，不增加性能负载。残余风险是文档与后续配置变更可能再次漂移，后续端口或部署变更必须同步 README 和对应专项文档。
@@ -0,0 +1,6 @@
+# 实施计划
+
+1. 对比 README 与当前部署、架构和功能档案。
+2. 执行 Schema 基线和 GitNexus 开发前影响分析。
+3. 更新 README 的状态、技术栈、TDX 隧道、启动和治理内容。
+4. 检查旧端口和敏感信息，执行格式检查和治理完成门禁。
@@ -0,0 +1,12 @@
+id: FEAT-MO-003
+name: README 文档同步
+slug: readme-refresh
+status: ready_for_release
+owner: project
+created_at: 2026-08-19
+requirements: requirements.md
+prd: prd.md
+design: design.md
+implementation_plan: implementation-plan.md
+release: unreleased
+traceability_note: README 事实边界、完整门禁、GitNexus 与独立 Review 已通过，等待正式版本发布
@@ -0,0 +1,45 @@
+# README 文档同步 PRD
+
+- 功能编号：FEAT-MO-003
+- PRD版本：0.1
+- 状态：approved
+- 日期：2026-08-19
+
+## 背景与问题
+
+根目录 README 仍使用旧的英文项目描述、旧的 5173 前端端口和过时的基础设施说明，无法指导当前 TDX 双隧道开发。
+
+## 产品目标
+
+- README 准确说明当前市场概览首屏能力和未覆盖的数据源边界。
+- README 准确说明 Vue/NestJS/TDX/MySQL/Redis/RocketMQ 技术栈和源码部署边界。
+- README 准确说明 8888 Web、3000 API、17710 TDX 回环入口和 Tailscale 外部场景。
+- README 提供可直接执行的本地启动、验证和治理入口。
+
+## 非目标
+
+- 不改变业务代码、接口、运行配置或生产部署。
+- 不把真实 Tailscale 地址、Windows 用户、Token、密码或私钥写入文档。
+
+## 功能需求
+
+| 编号 | 优先级 | 需求 | 可观察结果 |
+|---|---|---|---|
+| FR-001 | P0 | 更新当前实现和技术栈 | README 与 FEAT-MO-001、架构文档一致 |
+| FR-002 | P0 | 更新本地端口和启动命令 | README 使用 Web 8888、API 3000 |
+| FR-003 | P0 | 更新 TDX 双隧道说明 | README 只使用 SSH 别名和 127.0.0.1:17710 |
+| FR-004 | P1 | 更新验证入口 | Schema、治理、测试和部署文档可追溯 |
+
+## 安全策略与评估
+
+README 只记录占位符和回环地址，不记录凭据；明确 TDX 不暴露到公网，明确 Schema 只能访问开发库。
+
+## 性能目标与评估
+
+文档不进入运行时路径，不增加 API、TDX、Redis、MySQL 或 RocketMQ 负载。
+
+## 验收标准
+
+- README 不再把 5173 描述为当前 Web 端口。
+- README 包含 8888、TDX 外部隧道和当前首屏模块。
+- README 命令与现有 package scripts 和部署手册一致。
@@ -0,0 +1,15 @@
+# 测试结果
+
+- README 已包含当前端口 8888、API 3000、TDX 17710 和外部 Tailscale 入口。
+- README 已包含当前市场概览模块和数据源边界。
+- README 已包含本地启动、停止、Schema 和治理命令。
+- 未发现敏感凭据或真实隧道地址。
+- 完整门禁：`pnpm verify` 通过，包含格式、契约、类型、全部测试、前后端构建和 Playwright 4/4。
+
+## 安全验证
+
+保持 TDX 回环入口和开发库边界，没有写入真实地址或密钥。
+
+## 性能验证
+
+文档不进入运行时路径；格式检查、构建和 E2E 通过。
@@ -0,0 +1,11 @@
+# 视觉验证
+
+README 为 Markdown 文档，本次不执行页面视觉截图；已检查标题层级、代码块、链接和列表结构。
+
+## 安全验证
+
+文档只展示本机回环地址和占位符。
+
+## 性能验证
+
+文档内容不会影响前端运行时性能。
@@ -0,0 +1,3 @@
+# 发布说明
+
+README 已同步当前项目状态、8888 Web 端口、TDX 双隧道、本地启动和治理入口；无运行时行为变化。
@@ -0,0 +1,10 @@
+# 需求
+
+用户要求更新落后的 README。范围确定为同步当前已实施架构、市场概览、TDX 外部隧道、8888 前端端口、本地启动方式和开发治理入口。
+
+## 实际范围
+
+- 根 README 更新为中文为主的项目说明。
+- 补充 Vue 3/NestJS/TDX/MySQL/Redis/RocketMQ/源码部署信息。
+- 补充 TDX LAN/Tailscale 别名和 17710 回环入口。
+- 补充 Web 8888、API 3000、Scheduler/Worker 可选启动和验证命令。
@@ -0,0 +1,46 @@
+# 代码 Review
+
+- 功能编号：FEAT-MO-003
+- reviewer_type：self
+- reviewer：Codex
+- 日期：2026-08-19
+
+## 审查范围
+
+审查 README 的当前状态、启动命令、端口、TDX 隧道、基础设施边界和链接。
+
+## PRD 与设计符合性
+
+符合：README 与现有本地开发、TDX、架构和市场概览文档保持一致。
+
+## 发现
+
+| 严重程度 | 位置 | 问题 | 影响 | 处理 |
+|---|---|---|---|---|
+| 无 | - | 未发现本次范围内问题 | - | - |
+
+## 测试缺口
+
+未执行页面视觉验证；README 文档不改变页面。
+
+## 安全与残余风险
+
+未发现凭据；残余风险是未来配置变化需要同步文档。
+
+## 性能与资源影响
+
+无运行时影响。
+
+## GitNexus 与同步修改
+
+README upstream 风险 LOW、执行流 0；仅同步入口文档，没有跨模块代码变化。
+
+## 修复与复审
+
+独立 Review 发现 `gitnexus/impact-plan.md` 末尾残留未填写模板，已删除重复占位内容；最终复审又发现 README 将尚不存在的强势个股入口写成已预留，现已改为明确的未来范围。完整门禁通过，等待最终复审。
+
+## 最终结论
+
+最终独立复审确认 README 与现有实现一致，并明确强势个股尚未开发；无 Critical、Important 或 Minor 问题，`Ready to commit: Yes`。
+
+最终结论：passed
@@ -0,0 +1,32 @@
+# 开发规范符合性 Review
+
+- 功能编号：FEAT-MO-003
+- reviewer_type：self
+- reviewer：Codex
+- 日期：2026-08-19
+
+## 检查结果
+
+- [x] README 与已实施架构和开发文档一致。
+- [x] 未写入凭据、生产数据或真实隧道地址。
+- [x] 明确记录安全边界、性能影响和验证证据。
+- [x] GitNexus 开发前后流程已记录。
+- [x] 开发总结记录需求、范围、完成项、缺陷、延期项和验证证据。
+
+## 不符合项与处置
+
+GitNexus 开发前影响计划曾残留模板占位内容，已清理并保留实际 LOW 风险、0 执行流及逐项跨模块判断；完整门禁已通过，README 对强势个股未开发状态的表述已纠正。
+
+## 安全、性能与架构检查
+
+文档不改变运行时；安全边界和基础设施启用边界已说明。
+
+## GitNexus 与开发总结检查
+
+影响分析为 LOW，README 更新与功能档案一致。
+
+## 最终结论
+
+最终独立复审确认模板占位、安全边界和验证证据均已同步，无未关闭问题。
+
+最终结论：passed
@@ -0,0 +1,10 @@
+# 回退说明
+
+## 触发条件
+
+- README 与实际启动配置再次不一致。
+- 发现文档包含敏感信息或错误的生产承诺。
+
+## 回退步骤
+
+恢复 README 到本次修改前版本；不需要修改代码、数据库、Redis、RocketMQ 或 TDX 隧道。
@@ -0,0 +1,16 @@
+# 测试计划
+
+## 功能验证
+
+- 检查 README 包含 8888、3000、17710、Tailscale 别名和市场概览模块。
+- 检查 README 不再使用 5173 作为当前端口。
+- 检查命令和链接指向现有文件与 package scripts。
+
+## 安全验证
+
+- 扫描 README 和功能档案，确认不包含 Token、密码、真实外部地址或私钥。
+- 确认 README 保留回环监听、TDX 不公网暴露和开发库 Schema 边界。
+
+## 性能验证
+
+文档不参与运行时；执行 git diff --check 和项目文档/治理门禁，不做业务压测。