# card

**Repository Path**: oinkppig/card

## Basic Information

- **Project Name**: card
- **Description**: 简单纸牌小游戏
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 排一牌微信小游戏工程

当前工程技术方案：

- 原生微信小游戏
- Canvas 2D
- JavaScript 当前运行入口
- TypeScript 模块化源码骨架
- appid 暂使用 `touristappid`

## 文档

文档已统一归档到 `docs/`：

- `docs/card.md`：策划与开发需求草案
- `docs/prd.md`：正式产品需求文档
- `docs/tech-design.md`：技术开发文档
- `docs/tasks.md`：开发任务清单
- `docs/project-structure.md`：项目结构与阶段性运行策略
- `docs/refactor-plan.md`：阶段性解耦与迁移计划
- `docs/development-flow.md`：从当前阶段到上线完成的预期开发流程

## 当前运行方式

现阶段优先使用根目录 `game.js` 作为可直接运行的 Canvas 2D MVP 原型入口，不需要先执行 TypeScript 构建。

1. 打开微信开发者工具。
2. 导入当前目录：`C:\Users\oink\Desktop\game\oh\card`。
3. 项目类型选择「小游戏」。
4. appid 使用配置中的 `touristappid` 或你自己的测试 appid。
5. 编译运行后，点击「新游戏」开始测试。

## 当前 MVP 已包含

- 竖屏 4 列卡牌布局。
- 简单 / 普通难度。
- 开局至少有合法移动，并带有轻量初始局面筛选。
- 拖拽连续降序牌组移动。
- 始终维护底端 5 张明牌。
- 同色完整 9-1 自动收牌并计分。
- 无有效移动推进时弹窗提示。
- 撤回道具、无序道具、道具恢复、广告/分享奖励占位。
- 本地存档、继续游戏、历史最高轮分。

## 工程结构策略

- `game.js`：当前稳定可运行入口，优先保证微信开发者工具可编译、可操作。
- `src/`：TypeScript 模块化源码骨架，正在逐步沉淀配置、规则、道具、存档、分享/广告奖励、状态操作适配层和平台封装。
- `tests/`：核心纯逻辑自动化测试，已按 deck / rules / move / gameFlow / gameSession / props / save / share / adReward 拆分。
- `docs/`：需求、技术方案、任务清单、目录说明和重构计划。
- `assets/` / `textures/`：资源目录，后续接入正式美术和音效。

现阶段不强行切换到 TypeScript 构建入口；等核心逻辑测试稳定后，再逐步把 `game.js` 内联逻辑替换为模块化实现。

## 常用验证命令

```powershell
node --check .\game.js
npm.cmd test
npm.cmd run build
```


It is recommended to run the three commands above before each commit.

## Current Completion

This is a practice project. The project now focuses on a playable core loop, stable WeChat DevTools runtime, and reasonable code structure without over-engineering the UI.

### Done

- Core loop: new game, continue game, next level, restart, victory, and failure settlement.
- Core rules: descending stack movement, number-only normal target rule, and free placement on empty columns.
- Visibility rule: each column keeps the bottom 5 cards face-up.
- Collection rule: same-color 9-to-1 sequence at the column bottom is collected automatically.
- Difficulties: 1-color easy mode and 2-color normal mode.
- Props: disorder move, undo, 15-second recovery countdown, placeholder ad reward, and placeholder share reward.
- Save system: local save, continue game, background save, foreground recovery, and corrupted-save fallback cleanup.
- Feedback: basic drag/tap operation, move animation, collection fade-out, vibration, and placeholder sound.
- Engineering: core rules, flow, props, save, rewards, platform wrappers, and light UI pure helpers are organized under `src/`; core logic is covered by tests under `tests/`.

### Deferred / Out of Scope for Now

- Fully solvable deal generation.
- 4-color hard difficulty.
- Final art, themes, and complete sound effects.
- Real commercial ad unit integration.
- Real WeChat open-data leaderboard integration.
- Further UI over-componentization or complex render architecture.

## Manual Test Checklist

See `docs/manual-test-checklist.md` for a fuller checklist.

Recommended quick manual checks in WeChat DevTools after changing `game.js` or core flow:

- [ ] The project compiles and enters the main menu.
- [ ] New Game starts a playable board.
- [ ] Continue Game appears only when a valid local save exists.
- [ ] Easy / Normal difficulty selection affects the new board.
- [ ] Descending stacks can move; non-descending stacks cannot move.
- [ ] Normal target rule checks only card numbers.
- [ ] Empty columns accept any descending stack.
- [ ] Each column keeps the bottom 5 cards face-up.
- [ ] Same-color 9-to-1 sequence is collected as one group with fade-out.
- [ ] Victory, next level, restart, and failure settlement work.
- [ ] Disorder prop ignores only the target rule.
- [ ] Undo prop restores the full previous successful-move state.
- [ ] Prop recovery countdown updates.
- [ ] Placeholder ad/share rewards grant the selected prop.
- [ ] Background / foreground switching does not lose the board.
- [ ] Corrupted save data does not crash the game.

## TypeScript 后续流程

`src/` 已建立模块化骨架。后续迁移稳定逻辑后，可使用：

1. 安装依赖：`npm install`
2. 构建 TypeScript：`npm run build`
3. 根据迁移计划决定是否将构建产物接为正式运行入口