diff --git "a/docs/V26.0-\345\274\200\345\217\221\350\256\241\345\210\222.md" "b/docs/V26.0-\345\274\200\345\217\221\350\256\241\345\210\222.md" new file mode 100644 index 0000000..2240f04 --- /dev/null +++ "b/docs/V26.0-\345\274\200\345\217\221\350\256\241\345\210\222.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` 创建并归档。 diff --git "a/docs/V26.0-\351\234\200\346\261\202\350\257\264\346\230\216\344\271\246-v1.0.md" "b/docs/V26.0-\351\234\200\346\261\202\350\257\264\346\230\216\344\271\246-v1.0.md" new file mode 100644 index 0000000..aa7e966 --- /dev/null +++ "b/docs/V26.0-\351\234\200\346\261\202\350\257\264\346\230\216\344\271\246-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 可安装、可卸载、可升级。 +- 发布:含源码、构建记录、发布说明、已知问题与回滚方案。 diff --git a/docs/project/todo-v26.md b/docs/project/todo-v26.md new file mode 100644 index 0000000..b5c088e --- /dev/null +++ b/docs/project/todo-v26.md @@ -0,0 +1,30 @@ +# V26.0 Todo 看板 + +## 使用规则 +- 状态流:`Todo -> Doing -> Review -> Done` +- 所有任务必须有唯一 ID(`V26-Sx-Txx`)。 +- 发现 Bug 立刻登记到「Bug 列表」。 +- 进入下阶段前,P0/P1 必须闭环。 + +## 本周冲刺(S1 启动) + +| ID | 阶段 | 任务 | Owner | 依赖 | 完成标准 | 验证方式 | 状态 | 截止日期 | +|---|---|---|---|---|---|---|---|---| +| V26-S1-T01 | S1 | 输出需求说明书 v1.0 | PM/Tech | 无 | 文档评审通过 | 评审会议纪要 | Done | 2026-05-26 | +| V26-S1-T02 | S1 | 定义验收清单 | QA Lead | T01 | 覆盖功能/交互/数据/部署 | 验收清单签字 | Doing | 2026-05-27 | +| V26-S1-T03 | S1 | NFR 与本地资源边界确认 | Tech Lead | T01 | NFR 文档冻结 | 架构评审结论 | Todo | 2026-05-27 | +| V26-S1-T04 | S1 | 范围冻结与变更模板 | PM | T02 | 变更模板生效 | 版本委员会确认 | Todo | 2026-05-28 | + +## Bug 列表 + +| Bug ID | 级别 | 现象 | 影响范围 | 状态 | 修复负责人 | 下一步 | +|---|---|---|---|---|---|---| +| - | - | 暂无 | - | - | - | - | + +## 复盘记录 + +### 2026-05-25(S1 启动) +- 完成:V26-S1-T01(需求说明书初版)。 +- 遗留:验收清单与 NFR 尚未冻结。 +- 风险:围棋终局判定规则口径可能不一致。 +- 调整:先锁定 MVP 口径(中国规则+可配置贴目),再扩展。