新增 V26.0 版本开发计划、需求说明书与 Todo 看板文档

docs/V26.0-开发计划.md

@@ -0,0 +1,332 @@
+# V26.0 版本开发计划（多棋类本地应用：后端 + Windows Tauri 客户端）
+
+## 0. 版本目标与范围基线
+
+### 0.1 目标
+- 交付本地运行的多棋类游戏系统，支持：象棋、围棋、国际象棋。
+- 本次版本仅开发后端能力与 Windows 客户端（Tauri）。
+- 具备棋局记忆存储、胜负自动判断、实时评分、自定义开局、棋局编辑、轻量机器学习与推理能力。
+- 完成可复现构建、自动化部署、Windows 打包与发布文档。
+
+### 0.2 非目标（明确边界）
+- 不做多租户隔离设计。
+- 不追求高性能 AI 算法（以家庭电脑可运行为准）。
+- 不做云端部署（默认本地单机运行）。
+
+### 0.3 里程碑（建议 6 周 / 30 个工作日）
+- M1（第 1 周末）：需求冻结 + 架构评审通过。
+- M2（第 3 周末）：三棋类核心规则引擎可运行。
+- M3（第 4 周末）：评分、棋局编辑、开局管理、AI MVP 完成。
+- M4（第 5 周末）：端到端联调完成，进入缺陷收敛。
+- M5（第 6 周末）：自动化构建、打包、验收、发布完成。
+
+---
+
+## 1. 项目治理机制（全阶段强制执行）
+
+### 1.1 Todo 管理机制
+- 工具：`docs/project/todo-v26.md` + Issue 标签（`bug`、`blocker`、`risk`、`tech-debt`）。
+- 规则：
+  - 每个小任务必须有唯一 ID（如 `V26-S3-T12`）。
+  - 状态流转：`Todo -> Doing -> Review -> Done`。
+  - 每日收敛：未关闭问题必须给出「责任人 + 截止时间 + 下一步动作」。
+
+### 1.2 Bug 处理机制
+- 发现即登记：记录重现步骤、影响范围、优先级（P0/P1/P2）。
+- 分级策略：
+  - P0：阻塞主流程，立即插入修复队列。
+  - P1：影响核心功能，当日修复或给出规避方案。
+  - P2：可延期，但必须纳入后续 Sprint。
+- 闭环条件：修复后必须补充自动化测试或回归用例。
+
+### 1.3 阶段复盘机制
+- 每阶段结束输出 `阶段复盘记录`：
+  - 完成情况（Done/Undone）
+  - 遗留问题清单
+  - 风险与缓解措施
+  - 下一阶段调整（含原因）
+
+---
+
+## 2. 分阶段执行计划（含小时级任务）
+
+> 说明：以下按“阶段 → 小阶段（小时级）→ 任务明细”展开。每条均包含：做什么、完成标准、依赖、验证方式。
+
+## 阶段 S1：需求梳理与验收基线（预计 16h）
+
+### S1-1 需求工作坊（4h）
+- 做什么：梳理三棋类规则差异、评分定义、AI 目标、编辑器能力边界。
+- 完成标准：输出《V26 需求说明书 v1.0》。
+- 依赖：产品输入、示例棋谱。
+- 验证：评审会签字（产品/技术/测试）。
+
+### S1-2 验收标准定义（4h）
+- 做什么：建立最终验收清单（功能完整性、交互动线、数据联通、部署打包）。
+- 完成标准：形成可执行测试项（含通过/失败判定）。
+- 依赖：S1-1。
+- 验证：测试负责人确认可落地执行。
+
+### S1-3 非功能约束确认（4h）
+- 做什么：明确本地资源上限、启动时间、数据安全（本地存储）与备份策略。
+- 完成标准：写入 NFR 文档。
+- 依赖：S1-1。
+- 验证：技术评审通过。
+
+### S1-4 范围冻结与变更流程（4h）
+- 做什么：冻结 V26 范围，定义变更审批模板。
+- 完成标准：范围清单 + 变更单模板生效。
+- 依赖：S1-2。
+- 验证：版本委员会确认。
+
+**阶段验收（S1 Gate）**
+- 需求文档、验收文档、NFR、范围冻结文档齐全。
+- Todo 中 P0/P1 需求歧义为 0。
+
+---
+
+## 阶段 S2：架构设计与技术选型（预计 24h）
+
+### S2-1 总体架构设计（6h）
+- 做什么：定义模块边界：
+  - Rule Engine（规则引擎）
+  - Game State（状态管理）
+  - Scoring（评分）
+  - ML/Inference（轻量 AI）
+  - Persistence（棋局存储）
+  - Tauri API Gateway
+- 完成标准：架构图 + 调用链路图。
+- 依赖：S1 Gate。
+- 验证：架构评审通过。
+
+### S2-2 数据模型设计（6h）
+- 做什么：设计棋盘、走子记录、分支变体、开局模板、评分快照、对局记忆。
+- 完成标准：ER 图 + JSON Schema / DTO 定义。
+- 依赖：S2-1。
+- 验证：后端/客户端联合评审通过。
+
+### S2-3 技术栈落地（6h）
+- 做什么：
+  - 后端：Rust（Tauri backend commands）
+  - 前端：Tauri + TS + 组件库（如 Naive UI / Ant Design Vue / MUI）
+  - 图表：ECharts
+  - 国际化：i18n
+  - 主题：暗黑/明亮 + 动画系统
+- 完成标准：技术选型 ADR 文档。
+- 依赖：S2-1。
+- 验证：PoC 能跑通最小 Demo。
+
+### S2-4 安全与数据策略（6h）
+- 做什么：本地数据库（SQLite）加固、自动备份与恢复策略。
+- 完成标准：安全基线配置文档。
+- 依赖：S2-2。
+- 验证：恢复演练成功（含损坏修复方案）。
+
+**阶段验收（S2 Gate）**
+- 架构图、数据模型、ADR、PoC、数据策略文档完整。
+
+---
+
+## 阶段 S3：核心功能开发（预计 80h）
+
+### S3-1 三棋类规则引擎（24h）
+- 做什么：
+  - 象棋：行棋合法性、将军/将死、困毙
+  - 国际象棋：将军/将死/和棋、王车易位、吃过路兵、升变
+  - 围棋：落子合法性、提子、打劫、终局判定（简化贴目可配置）
+- 完成标准：规则单元测试覆盖率 ≥ 85%。
+- 依赖：S2 数据模型。
+- 验证：标准棋谱回放通过 + 随机对局稳定。
+
+### S3-2 胜负判定与实时评分（16h）
+- 做什么：统一 Result API 与评分 API（局势分、威胁分、地盘/子力分）。
+- 完成标准：每步可返回 `status + score + reason`。
+- 依赖：S3-1。
+- 验证：回放中评分曲线连续无断点。
+
+### S3-3 棋局记忆存储（12h）
+- 做什么：保存局面树、历史版本、标签、检索。
+- 完成标准：支持保存/读取/删除/导出。
+- 依赖：S2-2。
+- 验证：1000 局样本读写一致性通过。
+
+### S3-4 开局库与棋局编辑（16h）
+- 做什么：自定义开局、拖拽摆子、非法状态提示、保存为模板。
+- 完成标准：UI + API 联动完成。
+- 依赖：S3-1、S3-3。
+- 验证：编辑后可直接进入对弈并正确判定。
+
+### S3-5 轻量 AI 与推理（12h）
+- 做什么：实现 Minimax/Alpha-Beta（象棋/国际象棋），围棋简化策略（Monte Carlo light）。
+- 完成标准：可配置深度、可在家庭电脑实时响应（如 1~2 秒/步）。
+- 依赖：S3-1、S3-2。
+- 验证：与固定基准脚本对弈结果稳定。
+
+**阶段验收（S3 Gate）**
+- 三棋类最小闭环“建局→走子→判定→存档”全部可用。
+
+---
+
+## 阶段 S4：客户端体验与视觉完善（预计 56h）
+
+### S4-1 UI 信息架构（8h）
+- 做什么：大厅、对局、复盘、开局编辑、设置页面信息架构。
+- 完成标准：页面原型 + 路由定义。
+- 依赖：S1、S2。
+- 验证：交互评审通过。
+
+### S4-2 精美组件与主题系统（12h）
+- 做什么：构建 Design Token、主题切换（浅色/深色/高对比）。
+- 完成标准：全局主题一键切换不闪烁。
+- 依赖：S4-1。
+- 验证：视觉回归截图对比通过。
+
+### S4-3 多语言支持（8h）
+- 做什么：中文/英文文案资源、日期数字本地化。
+- 完成标准：核心页面 100% 覆盖。
+- 依赖：S4-1。
+- 验证：语言切换后无残留文案。
+
+### S4-4 动画与贴图（16h）
+- 做什么：落子动画、吃子动画、胜负特效、过渡动画、棋盘皮肤。
+- 完成标准：60fps 目标下主流程无卡顿。
+- 依赖：S4-2。
+- 验证：性能面板采样 + 用户走查。
+
+### S4-5 图表与分析视图（12h）
+- 做什么：评分曲线、胜率变化、关键手标注。
+- 完成标准：支持按步查看。
+- 依赖：S3-2。
+- 验证：回放时图表与棋步同步。
+
+**阶段验收（S4 Gate）**
+- 客户端具备“可用 + 好看 + 可分析”的完整交互体验。
+
+---
+
+## 阶段 S5：联调、测试、缺陷闭环（预计 64h）
+
+### S5-1 接口联调（12h）
+- 做什么：前后端接口契约校验，错误码统一。
+- 完成标准：联调清单项全部通过。
+- 依赖：S3、S4。
+- 验证：契约测试通过率 100%。
+
+### S5-2 自动化测试补齐（20h）
+- 做什么：单测、集成测试、端到端（Windows）。
+- 完成标准：核心模块覆盖率 ≥ 80%。
+- 依赖：S5-1。
+- 验证：CI 绿灯。
+
+### S5-3 主流程回归（16h）
+- 做什么：
+  - 新建对局
+  - 自定义开局
+  - 棋局编辑
+  - AI 对弈
+  - 复盘与评分
+  - 存档与恢复
+- 完成标准：主流程 0 阻塞缺陷。
+- 依赖：S5-2。
+- 验证：测试报告签字。
+
+### S5-4 Bug 冲刺（16h）
+- 做什么：清理 P0/P1 缺陷，复测回归。
+- 完成标准：P0=0，P1<=2（需有规避说明）。
+- 依赖：S5-3。
+- 验证：缺陷看板关闭状态可追踪。
+
+**阶段验收（S5 Gate）**
+- 可发布质量达标，关键路径稳定。
+
+---
+
+## 阶段 S6：自动化部署、打包与发布（预计 40h）
+
+### S6-1 构建流水线（12h）
+- 做什么：CI/CD（lint/test/build/package），产物归档。
+- 完成标准：主分支每次提交可自动构建。
+- 依赖：S5。
+- 验证：连续 3 次流水线通过。
+
+### S6-2 Windows 打包（10h）
+- 做什么：Tauri 打包（msi/exe），签名（如有证书）。
+- 完成标准：安装包可安装、可卸载、可升级。
+- 依赖：S6-1。
+- 验证：3 台不同配置机器安装验证通过。
+
+### S6-3 发布文档与复现记录（10h）
+- 做什么：发布说明、已知问题、回滚方案、构建记录。
+- 完成标准：文档齐全可复现。
+- 依赖：S6-2。
+- 验证：按文档在新机器复现成功。
+
+### S6-4 最终验收与交付（8h）
+- 做什么：组织最终验收会与交付清单签收。
+- 完成标准：验收报告通过。
+- 依赖：S6-3。
+- 验证：版本标签发布成功（V26.0）。
+
+**阶段验收（S6 Gate）**
+- 安装包、源码、文档、流水线、验收报告齐备。
+
+---
+
+## 3. 全量验收标准（Release Gate）
+
+### 3.1 功能完整性
+- 三棋类规则完整可用。
+- 胜负自动判断 + 实时评分正确可追溯。
+- 自定义开局、棋局编辑、记忆存储可用。
+- 轻量 AI 可稳定运行。
+
+### 3.2 交互与动线
+- 主要用户动线（建局→对弈→复盘→保存）无中断。
+- 多语言、主题切换、动画与贴图完整。
+
+### 3.3 数据与接口
+- 前后端接口联通率 100%。
+- 数据读写一致性、恢复能力达标。
+
+### 3.4 工程与发布
+- CI/CD 全绿。
+- Windows 安装包可安装、可运行、可卸载。
+- 已知问题完成回归并留档。
+
+---
+
+## 4. 风险清单与应对策略
+
+- 规则复杂度风险（围棋劫争、终局判定）：先交付可配置简化规则，预留增强点。
+- AI 性能风险：深度与搜索宽度做动态配置，提供“快速/标准”档。
+- 客户端动画性能风险：低配模式关闭部分粒子特效。
+- 跨模块联调风险：提前契约测试，日常小步联调。
+- 发布风险：预发布分支冻结 + 回滚脚本演练。
+
+---
+
+## 5. 执行用 Todo 模板（可直接落地）
+
+| ID | 阶段 | 任务 | Owner | 依赖 | 完成标准 | 验证方式 | 状态 | 备注 |
+|---|---|---|---|---|---|---|---|---|
+| V26-S3-T01 | S3 | 象棋规则合法性校验 | BE | S2-2 | 通过 200+ 样例 | 单测 + 棋谱回放 | Todo | |
+| V26-S4-T03 | S4 | 主题切换系统 | FE | S4-1 | 2 套主题无闪烁 | 视觉回归 | Todo | |
+| V26-S5-T08 | S5 | 主流程回归测试 | QA | S5-2 | 0 阻塞缺陷 | 回归报告 | Todo | |
+
+---
+
+## 6. 每阶段输出物清单
+- S1：需求说明书、验收标准、NFR、范围冻结清单。
+- S2：架构图、数据模型、ADR、PoC 报告。
+- S3：核心引擎代码、API 文档、规则测试报告。
+- S4：UI 设计稿、组件规范、动效资源、国际化资源。
+- S5：联调报告、自动化测试报告、缺陷收敛报告。
+- S6：CI/CD 配置、Windows 安装包、发布说明、回滚预案、最终验收报告。
+
+---
+
+## 7. 版本完成定义（Definition of Done）
+- 所有阶段 Gate 通过。
+- P0/P1 缺陷满足发布阈值。
+- 文档、源码、构建记录、安装包齐全。
+- 可在新环境按文档复现构建与运行。
+- 发布标签 `V26.0` 创建并归档。

docs/V26.0-需求说明书-v1.0.md

@@ -0,0 +1,60 @@
+# V26.0 需求说明书 v1.0
+
+## 1. 产品目标
+构建本地运行的多棋类游戏（象棋、围棋、国际象棋），交付后端能力与 Windows Tauri 客户端，支持对弈、复盘、评分、棋局编辑、开局模板和轻量 AI。
+
+## 2. 范围定义
+### 2.1 In Scope
+- 本地单机运行，不依赖云端。
+- 三棋类规则引擎。
+- 胜负自动判定与实时评分。
+- 棋局记忆存储（SQLite）。
+- 自定义开局与棋局编辑。
+- 轻量 AI（Minimax/Alpha-Beta + 围棋简化 Monte Carlo）。
+- Windows 打包安装（Tauri）。
+
+### 2.2 Out of Scope
+- 多租户隔离。
+- 云同步与在线对战。
+- 高算力 AI 模型训练。
+
+## 3. 核心功能需求
+### F1 对局管理
+- 新建对局：选择棋种、先后手、规则参数。
+- 对局状态：进行中、胜负已定、和局/终局。
+
+### F2 规则引擎
+- 象棋：行棋合法性、将军、将死、困毙。
+- 国际象棋：王车易位、升变、吃过路兵、将军/将死/和棋。
+- 围棋：落子合法、提子、打劫、终局（MVP 采用可配置贴目）。
+
+### F3 评分系统
+- 每步输出：`status + score + reason`。
+- 支持复盘评分曲线与关键手标记。
+
+### F4 棋局记忆
+- 保存、读取、删除、导出。
+- 支持局面树分支与标签检索。
+
+### F5 开局与编辑器
+- 拖拽摆子、非法状态提示。
+- 保存为开局模板并复用到新对局。
+
+### F6 AI 推理
+- 象棋/国际象棋：可配置深度搜索。
+- 围棋：轻量 Monte Carlo，家庭电脑 1~2 秒/步。
+
+### F7 客户端体验
+- 多语言（zh-CN/en-US）。
+- 主题切换（亮/暗）。
+- 动画：落子、吃子、胜负特效、页面过渡。
+
+## 4. 非功能需求（NFR）
+- 启动时间：冷启动 < 3s（中端家用电脑）。
+- 数据可靠性：异常退出后可恢复最近存档。
+- 可维护性：核心模块覆盖率目标 ≥ 80%。
+
+## 5. 验收口径（摘要）
+- 主流程：建局 -> 对弈 -> 判定 -> 评分 -> 存档 -> 复盘闭环可用。
+- 安装包：Windows 可安装、可卸载、可升级。
+- 发布：含源码、构建记录、发布说明、已知问题与回滚方案。