diff --git a/docs/deployment/local-development.md b/docs/deployment/local-development.md index 9a224d9..b810cc5 100644 --- a/docs/deployment/local-development.md +++ b/docs/deployment/local-development.md @@ -29,7 +29,7 @@ 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:5173/`。Scheduler 与 Worker 在 GOV-009 中保持 `ROCKETMQ_ENABLED=false`；没有经过验证的 Node RocketMQ 客户端时，启用配置会直接失败，不使用内存队列伪降级。 +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 客户端时，启用配置会直接失败，不使用内存队列伪降级。 ## 日常验证与停止 diff --git a/docs/features/FEAT-MO-002-web-port-8888/design.md b/docs/features/FEAT-MO-002-web-port-8888/design.md new file mode 100644 index 0000000..d4de5a1 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/design.md @@ -0,0 +1,21 @@ +# 设计 + +## 方案 + +在 `web/vite.config.ts` 的 `server.port` 设置 8888；同步 `web/playwright.config.ts` 的 `baseURL` 与 `webServer.url`，并更新 `docs/deployment/local-development.md`。保持 `host: 127.0.0.1`、`strictPort: true` 和 `/api` 代理不变。 + +## 安全策略与评估 + +- 监听地址仍为回环地址，不增加局域网或公网暴露。 +- 不停止 8080 的外部项目进程。 +- 不读取或写入凭据，不改变 API、TDX 或外部基础设施配置。 + +## 性能目标与评估 + +- 端口调整不改变前端构建产物和运行时逻辑。 +- Vite 启动验证目标为 30 秒内可访问；本次实际启动耗时小于 1 秒。 +- E2E 启动入口与真实监听地址保持一致，避免重复启动或等待错误端口。 + +## 错误处理与回退 + +`strictPort: true` 保持不变；8888 被占用时启动明确失败，不自动抢占或切换端口。回退时将四处当前配置恢复为 5173，并同步恢复文档。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/development-summary.md b/docs/features/FEAT-MO-002-web-port-8888/development-summary.md new file mode 100644 index 0000000..c3f37b2 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/development-summary.md @@ -0,0 +1,44 @@ +# Web 开发端口调整开发总结 + +- 功能编号：FEAT-MO-002 +- 总结版本：0.1 +- 日期：2026-08-19 + +## 原始开发需求 + +将前端端口改为 8080，检查占用并启动；经检查 8080 被其他项目占用后，用户确认改用 8888。 + +## 需求与范围变化 + +初始目标从 8080 调整为 8888，原因是 8080 已被另一个本地项目占用；该进程不属于本项目，本次没有停止或修改它。 + +## 实际完成需求 + +- `web/vite.config.ts` 开发端口改为 8888。 +- `web/playwright.config.ts` 两处 Web 地址改为 8888。 +- 本地开发手册 Web 地址改为 8888。 +- 新增端口回归测试。 +- Web 已在 `http://127.0.0.1:8888/` 启动并返回 200。 +- Tailscale 外部隧道已启动，SSH 控制隧道监听 `127.0.0.1:17710`，TDX 只读行情请求成功。 +- 为保证外部隧道切换后的 API 可重复启动，在被 Git 忽略的 `deploy/env/development/api.env.local` 补充了 `TDX_BASE_URL` 和 `TDX_TIMEOUT_MS`，未写入仓库。 + +## 修复缺陷 + +本次没有修复既有业务缺陷；变化属于本地开发配置和对应验证入口的一致性调整。新增回归断言防止端口意外恢复为 5173。 + +## 未完成与延期项 + +生产部署不在本次范围。完整 E2E 在收尾复验时发现市场概览夹具时钟未隔离，已由 `FEAT-QA-001` 修复；API 健康检查因开发 MySQL 不可用返回 503，但 Redis 正常，市场概览接口和 TDX 只读链路返回 200，MySQL 状态不属于本次端口变更。 + +## 关键提交 + +尚未提交；当前按用户要求完成本地修改和启动验证，提交与推送需在 Review 及用户确认后执行。 + +## 验证证据 + +- Schema：`npm run schema:baseline` 和 `npm run schema:verify` 均通过，版本 `v0.0.10 (captured_empty)`。 +- GitNexus：开发前索引状态最新；开发后检测为 LOW、受影响执行流 0。 +- 测试：Web Vitest 8 个文件、21 个测试通过；修改前新增端口测试按预期失败。 +- 启动：Vite 监听 8888，首页 HTTP 200；API 使用本地配置启动并监听 3000。 +- TDX：Tailscale ping 经 DERP 成功，SSH 隧道监听 17710，`get_market_data` 返回 `ErrorId=0`。 +- 安全：保持 127.0.0.1，不停止其他项目，不读取凭据。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/gitnexus/after.md b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/after.md new file mode 100644 index 0000000..2fc286f --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/after.md @@ -0,0 +1,13 @@ +# GitNexus 开发后基线 + +## GitNexus 状态 + +完成 Web 配置、测试和文档修改后刷新索引：3,122 nodes、4,343 edges、68 clusters、85 flows，状态 `up-to-date`。本功能影响评估为 LOW，受影响执行流为 0。 + +## Git 已跟踪变更摘要 + +Vite 开发端口、Playwright Web 地址和本地开发手册由 5173 统一调整为 8888；AGENTS.md 的既有修改保留，不属于本功能。 + +## Git 工作区摘要 + +工作区包含本功能档案和端口相关修改；无关未跟踪文件明确排除。提交与推送将在最终独立 Review 通过后执行。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/gitnexus/before.md b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/before.md new file mode 100644 index 0000000..ccd0fad --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/before.md @@ -0,0 +1,26 @@ +# GitNexus 开发前基线 + +- 功能编号：FEAT-MO-002 +- 记录时间：2026年8月19日 GMT+8 12:23:44 +- 分支：main +- 基线提交：1f6ed00e6fbb + +## 工作区 + +```text +M AGENTS.md +``` + +## GitNexus 状态 + +```text +Repository: +Indexed: 8/18/2026, 9:31:53 PM +Indexed commit: 1f6ed00 +Current commit: 1f6ed00 +Status: ✅ up-to-date +``` + +## 后续人工分析 + +在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/gitnexus/comparison.md b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/comparison.md new file mode 100644 index 0000000..9860868 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/comparison.md @@ -0,0 +1,13 @@ +# GitNexus 前后对比 + +## 开发前 + +Vite 监听 5173，Playwright 和本地手册使用 5173；GitNexus 索引为项目当前基线。 + +## 开发后 + +Vite、Playwright 和本地开发手册统一使用 8888；业务模块执行流、API 契约和数据基础设施不变。GitNexus 变更检测为 LOW，受影响执行流 0。 + +## 差异处置 + +8080 的外部 Python 进程未被停止；Tailscale 外部 TDX 隧道独立切换到 `tdx-windows-tailnet`，不改变平台固定的 127.0.0.1:17710 入口。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/gitnexus/detected-changes.md b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/detected-changes.md new file mode 100644 index 0000000..2257edc --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/detected-changes.md @@ -0,0 +1,9 @@ +# GitNexus 变更检测 + +执行：`gitnexus_detect_changes({scope: "unstaged", repo: "a-share-analysis"})`。 + +结果：`changed_count=3`、`changed_files=5`、`affected_count=0`、`risk_level=low`、受影响执行流 0。GitNexus 识别到 AGENTS.md（既有工作区修改）和本地开发文档章节；Vite/Playwright 的端口常量变化未映射为业务符号，已通过配置测试、类型检查、构建和 HTTP 启动验证覆盖。 + +本功能预期变更仅为：Vite 端口、Vite 配置测试、Playwright 地址、本地开发文档和功能档案。AGENTS.md 是用户已有修改，本次不触碰其内容，也不将其视为功能变更。 + +同步判断：不涉及 API/OpenAPI、消息契约、数据库、Redis、Scheduler、Worker 或生产部署；Web 开发启动流程已同步。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/gitnexus/impact-plan.md b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/impact-plan.md new file mode 100644 index 0000000..ff61638 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/gitnexus/impact-plan.md @@ -0,0 +1,35 @@ +# GitNexus 开发前影响计划 + +- 功能编号：FEAT-MO-002 +- 目标：将 Vue/Vite 本地开发服务器端口从 5173 调整为 8888。 +- 总体风险：LOW + +## 直接与间接影响 + +- `gitnexus_query("Vite development server port web startup")` 定位到 `web/vite.config.ts` 和 `web/src/vite-config.test.ts`。 +- `gitnexus_context({name: "vite.config.ts", file_path: "web/vite.config.ts"})` 显示该配置文件被 `web/src/vite-config.test.ts` 导入，配置内部调用 `readDevelopmentPublicEnv`。 +- `gitnexus_impact({target: "vite.config.ts", direction: "upstream"})`：直接调用方 0、受影响执行流 0、受影响模块 0，风险 LOW。 +- `gitnexus_impact({target: "playwright.config.ts", direction: "upstream"})`：直接调用方 0、受影响执行流 0、受影响模块 0，风险 LOW；该配置自身启动并访问 Web 开发服务器，需要同步更新端口。 +- 对 `readDevelopmentPublicEnv` 的 upstream 影响为 1 个配置文件调用方，风险 LOW；端口字段是 Vite 配置常量，不改变 API、数据契约或业务逻辑。 +- 8080 已被另一个本地项目占用；该进程不属于本项目，本次不停止、不修改，也不记录其本机目录或临时进程标识。 + +## 跨模块同步修改 + +| 维度 | 判断 | 同步修改 | +|---|---|---| +| HTTP/OpenAPI | 不涉及页面 API 契约 | 无 | +| Web API | 不涉及 Axios 请求路径 | 无 | +| 消息契约 | 不涉及 RocketMQ | 无 | +| 数据库 | 不涉及 MySQL Schema | 无 | +| Redis | 不涉及缓存 | 无 | +| API | Nest API 端口保持 3000 | 无 | +| Scheduler/Worker | 不涉及任务进程 | 无 | +| 部署 | 仅开发 Vite 端口；生产 Web 配置不变 | 更新本功能说明 | +| 测试 | Vite 配置回归测试增加 8888 断言；Playwright baseURL/webServer URL 同步 | 修改 `web/src/vite-config.test.ts`、`web/playwright.config.ts` | +| 文档 | 本地开发 Web 地址同步为 8888 | 修改 `docs/deployment/local-development.md` 和本功能档案 | + +## 安全、性能与残余风险 + +- 安全：不改变监听地址（仍为 `127.0.0.1`），不暴露新公网入口，不接触凭据。 +- 性能：仅改变本地开发服务器监听端口，不改变构建产物、代理或运行时性能。 +- 残余风险：如果其他本地进程占用 8888，因 `strictPort: true` 启动会失败；启动前必须检测并报告。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/implementation-plan.md b/docs/features/FEAT-MO-002-web-port-8888/implementation-plan.md new file mode 100644 index 0000000..56be620 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/implementation-plan.md @@ -0,0 +1,9 @@ +# 实施计划 + +1. 检查 8080/8888 占用情况和工作区状态。 +2. 执行 Schema 基线与校验，运行治理起始门禁。 +3. 使用 GitNexus 评估 Vite、Playwright 配置和测试影响。 +4. 先添加 8888 回归断言并确认旧配置下失败，再修改 Vite 配置。 +5. 同步 Playwright 和本地开发文档。 +6. 启动 Web，验证 8888 HTTP 200；切换 Tailscale 外部 TDX 隧道并验证只读行情。 +7. 执行测试、构建、GitNexus 变更检测和 Review。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/manifest.yaml b/docs/features/FEAT-MO-002-web-port-8888/manifest.yaml new file mode 100644 index 0000000..98aef29 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/manifest.yaml @@ -0,0 +1,12 @@ +id: FEAT-MO-002 +name: Web 开发端口调整为 8888 +slug: web-port-8888 +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: 端口配置、安全断言、完整门禁、GitNexus 与独立 Review 已通过，等待正式版本发布 diff --git a/docs/features/FEAT-MO-002-web-port-8888/prd.md b/docs/features/FEAT-MO-002-web-port-8888/prd.md new file mode 100644 index 0000000..9320ce9 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/prd.md @@ -0,0 +1,47 @@ +# Web 开发端口调整为 8888 PRD + +- 功能编号：FEAT-MO-002 +- PRD版本：0.1 +- 状态：approved +- 日期：2026-08-19 + +## 背景与问题 + +本机 8080 已被其他项目占用，现有 A 股分析工具前端开发端口 5173 需要调整为用户指定的 8888。 + +## 产品目标 + +- Web 开发服务器监听 `127.0.0.1:8888`。 +- Playwright、本地开发文档和端口回归测试使用同一地址。 +- API 仍监听 `127.0.0.1:3000`，TDX 隧道仍使用 `127.0.0.1:17710`。 + +## 非目标 + +- 不改变生产 Web 端口、Nginx、API、TDX、Redis、MySQL 或 RocketMQ 配置。 +- 不停止其他项目进程，不开放公网监听。 + +## 功能需求 + +| 编号 | 优先级 | 需求 | 可观察结果 | +|---|---|---|---| +| FR-001 | P0 | 调整 Vite 开发端口 | `vite.config.ts` 的 `server.port` 为 8888 | +| FR-002 | P0 | 同步 E2E 和本地文档 | Playwright 和开发手册访问 8888 | +| FR-003 | P0 | 保持本机安全边界 | host 仍为 127.0.0.1，strictPort 仍启用 | + +## 安全需求与信任边界 + +本次只改变本机开发监听端口，不改变监听地址、代理目标、认证、数据源或凭据。8080 占用进程不属于本项目，不停止或操作该进程。 + +## 性能目标与容量假设 + +端口变化不应改变构建、代理和页面运行时性能；Vite 应在 30 秒内启动并返回首页。 + +## 验收标准 + +- `web/src/vite-config.test.ts` 断言端口为 8888。 +- `http://127.0.0.1:8888/` 返回 HTTP 200。 +- API 代理仍转发到 `http://127.0.0.1:3000`。 + +## 关联模块与同步修改 + +涉及 Web Vite 配置、Web 配置测试、Playwright 配置和本地开发文档；不涉及 HTTP/OpenAPI、数据库、Redis、消息、Scheduler、Worker 和生产部署。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/qa/test-results.md b/docs/features/FEAT-MO-002-web-port-8888/qa/test-results.md new file mode 100644 index 0000000..7f71470 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/qa/test-results.md @@ -0,0 +1,19 @@ +# 测试结果 + +- RED：端口断言在旧配置下按预期失败，实际值为 5173，期望值为 8888。 +- GREEN：Web Vitest 8 个测试文件、21 个测试全部通过。 +- 安全回归：Vite 配置测试同时锁定 `host=127.0.0.1`、`port=8888` 和 `strictPort=true`。 +- HTTP：`curl -I http://127.0.0.1:8888/` 返回 HTTP 200。 +- API：`/api/v1/market-overview/summary` 返回 HTTP 200，`source=tdx`、`status=fresh`。 +- TDX：外部 Tailscale SSH 隧道 `127.0.0.1:17710` 只读请求返回 `ErrorId=0`。 +- 健康检查：API 返回 503，明确原因为开发 MySQL 不可用；Redis 为 healthy，RocketMQ 为 disabled。该结果不影响端口和 TDX 链路验收。 +- 完整门禁：`pnpm verify` 通过，Web 21/21、Server 67/67、启动器 2/2、Playwright 4/4，类型检查与前后端构建通过。 +- Lint：0 error；保留市场概览组件既有 35 条格式 warning，本功能没有新增 warning。 + +## 安全验证 + +监听地址保持回环；未停止或修改占用 8080 的外部进程；变更中未写入新凭据、本机绝对路径或临时进程标识。 + +## 性能验证 + +Vite 启动耗时约 194ms，首页可立即访问；完整构建和 E2E 通过，未增加运行时依赖和外部服务调用。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/qa/visual-qa.md b/docs/features/FEAT-MO-002-web-port-8888/qa/visual-qa.md new file mode 100644 index 0000000..21a8344 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/qa/visual-qa.md @@ -0,0 +1,11 @@ +# 视觉验证 + +本次仅改变开发服务器端口，不改变页面布局、样式或组件。收尾的 Playwright 在桌面与移动端共执行 4 个用例并全部通过；页面视觉基线继续沿用 FEAT-MO-001 的既有截图，不制造重复截图产物。 + +## 安全验证 + +Web 仍只绑定 `127.0.0.1`，没有新增局域网或公网访问入口。 + +## 性能验证 + +Vite 监听 8888 后首页响应正常，端口变更不影响页面资源加载路径。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/release-notes.md b/docs/features/FEAT-MO-002-web-port-8888/release-notes.md new file mode 100644 index 0000000..917fa3b --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/release-notes.md @@ -0,0 +1,3 @@ +# 发布说明 + +本地开发 Web 端口从 5173 调整为 8888。API、TDX 隧道和生产配置不变。该功能尚未创建发布标签。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/requirements.md b/docs/features/FEAT-MO-002-web-port-8888/requirements.md new file mode 100644 index 0000000..34fb675 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/requirements.md @@ -0,0 +1,14 @@ +# 需求 + +用户要求将前端开发端口改为 `8888`，检查是否被占用并启动项目。 + +## 实际范围 + +- Vite 开发服务器从 5173 改为 8888。 +- Playwright `baseURL` 和 Web Server 检查地址同步为 8888。 +- 本地开发手册 Web 地址同步为 8888。 +- API 继续使用 3000，TDX 外部隧道继续映射到 17710。 + +## 范围变化 + +8080 初次检查发现已被其他项目 Python `run.py` 进程占用，因此没有停止该进程，改用用户确认的 8888。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/review/code-review.md b/docs/features/FEAT-MO-002-web-port-8888/review/code-review.md new file mode 100644 index 0000000..b8b524e --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/review/code-review.md @@ -0,0 +1,46 @@ +# 代码 Review + +- 功能编号：FEAT-MO-002 +- reviewer_type：self +- reviewer：Codex +- 日期：2026-08-19 + +## 审查范围 + +审查 `web/vite.config.ts`、`web/src/vite-config.test.ts`、`web/playwright.config.ts`、本地开发手册及对应功能档案。 + +## PRD 与设计符合性 + +符合：Vite、Playwright 和本地开发文档统一使用 8888，API 3000、TDX 隧道 17710 和回环监听保持不变。 + +## 发现 + +| 严重程度 | 位置 | 问题 | 影响 | 处理 | +|---|---|---|---|---| +| 无 | - | 未发现本次范围内问题 | - | - | + +## 测试缺口 + +收尾时完整 E2E 首次运行发现市场概览测试夹具时钟未隔离；该跨日缺陷不属于端口行为，已由 `FEAT-QA-001` 使用固定测试时钟修复并纳入完整门禁。 + +## 安全与残余风险 + +保持 `127.0.0.1` 和 `strictPort`，不停止其他项目。残余风险是 8888 被其他进程占用时启动会明确失败。 + +## 性能与资源影响 + +仅改变监听端口；Vite 启动约 194ms，无新依赖和外部负载。 + +## GitNexus 与同步修改 + +GitNexus 对 Vite 和 Playwright 配置影响评估为 LOW；同步更新了配置测试、E2E 地址和本地开发文档。 + +## 修复与复审 + +端口测试已完成 RED/GREEN；独立 Review 要求补锁回环地址和 `strictPort`，对应断言已增加。档案中的本机绝对路径、临时 PID 和旧验证结论已清理；完整门禁通过，等待最终复审。 + +## 最终结论 + +最终独立复审确认回环监听、8888、`strictPort`、Playwright 和文档一致；无 Critical、Important 或 Minor 问题，`Ready to commit: Yes`。 + +最终结论：passed diff --git a/docs/features/FEAT-MO-002-web-port-8888/review/standards-review.md b/docs/features/FEAT-MO-002-web-port-8888/review/standards-review.md new file mode 100644 index 0000000..67ad0d7 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/review/standards-review.md @@ -0,0 +1,36 @@ +# 开发规范符合性 Review + +- 功能编号：FEAT-MO-002 +- reviewer_type：self +- reviewer：Codex +- 日期：2026-08-19 + +## 检查结果 + +- [x] 必要中文注释准确且没有逐行废话注释。 +- [x] 文件按稳定职责拆分，没有过度碎片化。 +- [x] 端口、监听地址和时间语义明确。 +- [x] 错误处理和 strictPort 行为保持不变。 +- [x] 安全策略、性能目标、验证证据和残余风险完整。 +- [x] 未引入依赖，未发生 API 或前端请求边界变化。 +- [x] GitNexus 开发前影响分析和开发后检测已记录，风险 LOW、0 受影响执行流。 +- [x] 开发总结记录了需求、范围变化、完成项、延期项和验证证据。 +- [x] PRD、设计、测试、发布和回退口径一致。 + +## 不符合项与处置 + +独立 Review 发现安全配置断言不足、功能档案含本机绝对路径/临时 PID 且验证结论已过时。现已清理敏感环境细节并补充 `host`、`port`、`strictPort` 回归断言；完整门禁通过，等待最终复审。 + +## 安全、性能与架构检查 + +监听仍为 127.0.0.1；端口变化不改变资源性能；8080 外部进程未被操作。 + +## GitNexus 与开发总结检查 + +影响风险 LOW，配置、测试、E2E 和文档同步修改均已记录；开发总结列出 TDX 外部隧道与 MySQL 健康检查证据。 + +## 最终结论 + +最终独立复审确认完整门禁、GitNexus、安全清理和逐路径提交策略符合规范；无未关闭问题。 + +最终结论：passed diff --git a/docs/features/FEAT-MO-002-web-port-8888/rollback.md b/docs/features/FEAT-MO-002-web-port-8888/rollback.md new file mode 100644 index 0000000..0fd940e --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/rollback.md @@ -0,0 +1,19 @@ +# 回退说明 + +## 触发条件 + +- 8888 与本机其他必要服务冲突。 +- Playwright 或本地开发脚本无法访问前端。 +- 发现端口改动影响非开发环境配置。 + +## 回退步骤 + +1. 将 `web/vite.config.ts` 的 `server.port` 恢复为 5173。 +2. 将 `web/playwright.config.ts` 的 `baseURL` 和 `webServer.url` 恢复为 5173。 +3. 将 `docs/deployment/local-development.md` 的 Web 地址恢复为 5173。 +4. 同步修改端口回归测试和本功能档案，执行 Web 测试与启动验证。 +5. 停止本功能启动的 Web 进程，不操作 8080 的其他项目。 + +## 数据与外部服务 + +本次不修改 MySQL、Redis、RocketMQ、TDX 客户端或 SSH 隧道配置，因此无需数据回退。 diff --git a/docs/features/FEAT-MO-002-web-port-8888/test-plan.md b/docs/features/FEAT-MO-002-web-port-8888/test-plan.md new file mode 100644 index 0000000..e636d33 --- /dev/null +++ b/docs/features/FEAT-MO-002-web-port-8888/test-plan.md @@ -0,0 +1,22 @@ +# 测试计划 + +## 功能验证 + +- Vite 配置单元测试：监听地址为 `127.0.0.1`、端口为 8888、`strictPort=true`，代理仍为本地 API。 +- Web 启动验证：8888 返回首页 HTML。 +- Playwright 配置检查：baseURL 和 webServer URL 均为 8888。 + +## 安全验证 + +- 检查监听地址仍为 `127.0.0.1`。 +- 检查 8080 外部 Python 进程未被停止或修改。 +- 检查无密钥、密码和公网地址进入变更文件。 + +## 性能验证 + +- 记录 Vite 启动耗时和首页 HTTP 响应。 +- 端口配置不引入新依赖、不增加 API 或数据源负载。 + +## 验证边界 + +生产部署验证不属于本地开发端口范围；收尾时仍执行完整仓库门禁和 Playwright 桌面/移动端回归，确保端口同步没有破坏测试启动链路。 diff --git a/web/playwright.config.ts b/web/playwright.config.ts index bf91966..5a81c9d 100644 --- a/web/playwright.config.ts +++ b/web/playwright.config.ts @@ -6,7 +6,7 @@ export default defineConfig({ retries: 0, reporter: 'list', use: { - baseURL: 'http://127.0.0.1:5173', + baseURL: 'http://127.0.0.1:8888', trace: 'retain-on-failure', }, webServer: [ @@ -18,7 +18,7 @@ export default defineConfig({ }, { command: 'env -u NO_COLOR pnpm dev', - url: 'http://127.0.0.1:5173', + url: 'http://127.0.0.1:8888', reuseExistingServer: false, timeout: 30_000, }, diff --git a/web/src/vite-config.test.ts b/web/src/vite-config.test.ts index 295b5b5..801f090 100644 --- a/web/src/vite-config.test.ts +++ b/web/src/vite-config.test.ts @@ -16,4 +16,10 @@ describe('Vite 本地 API 代理', () => { }, }); }); + + it('本地开发服务器只在回环地址严格监听 8888 端口', () => { + expect(viteConfig.server?.host).toBe('127.0.0.1'); + expect(viteConfig.server?.port).toBe(8888); + expect(viteConfig.server?.strictPort).toBe(true); + }); }); diff --git a/web/vite.config.ts b/web/vite.config.ts index 5b314cd..4930485 100644 --- a/web/vite.config.ts +++ b/web/vite.config.ts @@ -40,7 +40,7 @@ export default defineConfig({ ), server: { host: '127.0.0.1', - port: 5173, + port: 8888, strictPort: true, proxy: { // 本地浏览器始终请求同源 /api，由 Vite 转发到 NestJS，避免开发环境放宽 CORS。