@creatoria/miniapp-mcp 0.1.2 → 0.2.0

package/docs/tasks.A4.atomize.md

@@ -1,496 +0,0 @@
-# Task Cards: A4 - 搭建 lint / format / commit hooks
-# Parent Task: TASK-2025-001-A4
-# Stage: Atomize (原子化阶段)
-# Status: RETROSPECTIVE (追溯补齐)
-# Created: 2025-10-02 (追溯)
-
----
-
-## Overview (概览)
-
-本文档包含 A4 任务的原子化拆解，将"搭建 lint / format / commit hooks（可选）"拆分为 4 个可独立执行的子任务。每个任务估算时间为 10-20 分钟，总计约 55 分钟（如包含可选的 hook 配置），符合 Atomize 原则（1-3 小时颗粒度）。
-
-**注意**：任务 A4-4（配置 pre-commit hook）标记为可选，实际未实现。
-
-**注**: 本文档为追溯性创建，基于已完成的实际产物（配置文件）进行反推。
-
----
-
-## Task Card 1: 配置 ESLint
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A4-1
-Title: 配置 ESLint 和 TypeScript 规则
-Priority: HIGH
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 20 分钟
-Actual: ~20 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- ESLint 提供代码静态检查，发现潜在错误
-- TypeScript 专用规则增强类型安全
-- 统一代码风格，减少代码审查负担
-
-**Input (输入)**:
-- TypeScript 项目配置（tsconfig.json）
-- 项目结构（src/, tests/）
-- Prettier 配置（需要避免冲突）
-
-**Output (输出)**:
-- `.eslintrc.cjs` (29 行)
-- package.json 更新（ESLint 依赖和 scripts）
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-
-1. 安装 ESLint 依赖
-   - eslint: ^8.57.0
-   - @typescript-eslint/parser: ^7.13.1
-   - @typescript-eslint/eslint-plugin: ^7.13.1
-   - eslint-config-prettier: ^9.1.0
-
-2. 创建 `.eslintrc.cjs` 配置文件
-   - 使用 CommonJS 格式（.cjs）避免 ESM 问题
-   - parser: '@typescript-eslint/parser'
-   - extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier']
-   - plugins: ['@typescript-eslint']
-   - parserOptions: project tsconfig, ES2022, module
-   - env: node, es2022, jest
-
-3. 配置自定义规则
-   - @typescript-eslint/no-explicit-any: 'warn' （警告，不阻止开发）
-   - @typescript-eslint/no-unused-vars: ['error', {argsIgnorePattern: '^_', varsIgnorePattern: '^_'}]
-   - no-console: 'off' （允许 console.log）
-
-4. 配置忽略模式
-   - ignorePatterns: ['dist', 'node_modules', '*.cjs']
-
-5. 添加 package.json script
-   - scripts.lint: "eslint . --ext .ts"
-
-**Actual Implementation (实际实现)**:
-
-**.eslintrc.cjs**:
-```javascript
-module.exports = {
-  parser: '@typescript-eslint/parser',
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'prettier'
-  ],
-  plugins: ['@typescript-eslint'],
-  parserOptions: {
-    ecmaVersion: 2022,
-    sourceType: 'module',
-    project: './tsconfig.json'
-  },
-  env: {
-    node: true,
-    es2022: true,
-    jest: true
-  },
-  rules: {
-    '@typescript-eslint/no-explicit-any': 'warn',
-    '@typescript-eslint/no-unused-vars': ['error', {
-      argsIgnorePattern: '^_',
-      varsIgnorePattern: '^_'
-    }],
-    'no-console': 'off'
-  },
-  ignorePatterns: ['dist', 'node_modules', '*.cjs']
-}
-```
-
-**package.json** (relevant sections):
-```json
-{
-  "scripts": {
-    "lint": "eslint . --ext .ts"
-  },
-  "devDependencies": {
-    "eslint": "^8.57.0",
-    "@typescript-eslint/eslint-plugin": "^7.13.1",
-    "@typescript-eslint/parser": "^7.13.1",
-    "eslint-config-prettier": "^9.1.0"
-  }
-}
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] `.eslintrc.cjs` 文件存在
-- [x] parser 设置为 '@typescript-eslint/parser'
-- [x] extends 包含 eslint:recommended, @typescript-eslint/recommended, prettier
-- [x] plugins 包含 '@typescript-eslint'
-- [x] parserOptions 指向 tsconfig.json
-- [x] env 包含 node, es2022, jest
-- [x] rules 配置 no-explicit-any: warn
-- [x] rules 配置 no-unused-vars: error（带 _ 前缀忽略）
-- [x] ignorePatterns 排除 dist, node_modules
-- [x] package.json 包含 ESLint 依赖
-- [x] package.json.scripts 包含 lint
-- [x] `pnpm lint` 成功运行，检测代码问题
-
-### Risks (风险)
-
-- ⚠️ **ESLint 规则过于严格**
-  - 缓解: no-explicit-any 设为 warn（警告）
-
-- ⚠️ **与 Prettier 规则冲突**
-  - 缓解: 使用 eslint-config-prettier 禁用冲突规则
-
----
-
-## Task Card 2: 配置 Prettier
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A4-2
-Title: 配置 Prettier 代码格式化
-Priority: HIGH
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 15 分钟
-Actual: ~15 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- Prettier 自动格式化代码，统一风格
-- 减少代码审查中的风格争议
-- 提高代码可读性
-
-**Input (输入)**:
-- 项目代码库（src/, tests/）
-- 主流 TypeScript/JavaScript 风格规范
-- 需要排除的目录（docs/, dist/ 等）
-
-**Output (输出)**:
-- `.prettierrc` (10 行)
-- `.prettierignore` (8 行)
-- package.json 更新（Prettier 依赖和 scripts）
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-
-1. 安装 Prettier 依赖
-   - prettier: ^3.3.2
-
-2. 创建 `.prettierrc` 配置文件
-   - semi: false （不使用分号）
-   - singleQuote: true （单引号）
-   - printWidth: 100 （每行最大 100 字符）
-   - trailingComma: 'es5' （ES5 兼容的尾逗号）
-   - tabWidth: 2 （缩进 2 空格）
-   - useTabs: false （使用空格）
-   - arrowParens: 'always' （箭头函数总是带括号）
-   - endOfLine: 'lf' （LF 换行符）
-
-3. 创建 `.prettierignore` 排除规则
-   - node_modules, dist, coverage, *.log, .DS_Store, .llm, docs
-
-4. 添加 package.json scripts
-   - scripts.format: "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
-   - scripts.format:check: "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\""
-
-**Actual Implementation (实际实现)**:
-
-**.prettierrc**:
-```json
-{
-  "semi": false,
-  "trailingComma": "es5",
-  "singleQuote": true,
-  "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false,
-  "arrowParens": "always",
-  "endOfLine": "lf"
-}
-```
-
-**.prettierignore**:
-```
-node_modules
-dist
-coverage
-*.log
-.DS_Store
-.llm
-docs
-```
-
-**package.json** (relevant sections):
-```json
-{
-  "scripts": {
-    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\""
-  },
-  "devDependencies": {
-    "prettier": "^3.3.2"
-  }
-}
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] `.prettierrc` 文件存在
-- [x] semi: false
-- [x] singleQuote: true
-- [x] printWidth: 100
-- [x] trailingComma: 'es5'
-- [x] tabWidth: 2
-- [x] useTabs: false
-- [x] arrowParens: 'always'
-- [x] endOfLine: 'lf'
-- [x] `.prettierignore` 文件存在
-- [x] 排除 node_modules, dist, coverage, docs
-- [x] package.json 包含 Prettier 依赖
-- [x] package.json.scripts 包含 format, format:check
-- [x] `pnpm format:check` 成功运行，检测格式问题
-- [x] `pnpm format` 可格式化代码
-
-### Risks (风险)
-
-- ⚠️ **格式化破坏特殊格式的文档**
-  - 缓解: .prettierignore 排除 docs/
-
----
-
-## Task Card 3: 安装 Husky
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A4-3
-Title: 安装 Husky Git Hooks 框架
-Priority: MEDIUM
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 10 分钟
-Actual: ~10 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- Husky 简化 Git Hooks 配置
-- 为未来自动化检查预留（pre-commit, pre-push 等）
-- 标准化团队 Git 工作流
-
-**Input (输入)**:
-- Git 仓库
-- package.json
-
-**Output (输出)**:
-- .husky/ 目录
-- package.json 更新（Husky 依赖和 prepare script）
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-
-1. 安装 Husky 依赖
-   - husky: ^9.0.11
-
-2. 添加 prepare script
-   - scripts.prepare: "husky install"
-   - npm install 时自动运行
-
-3. 运行 prepare 初始化 Husky
-   - 创建 .husky/ 目录
-   - 生成 husky 模板文件
-
-**Actual Implementation (实际实现)**:
-
-**package.json** (relevant sections):
-```json
-{
-  "scripts": {
-    "prepare": "husky install"
-  },
-  "devDependencies": {
-    "husky": "^9.0.11"
-  }
-}
-```
-
-**.husky/ Directory**:
-```
-.husky/
-  └── _/           # Husky 模板文件
-      ├── .gitignore
-      ├── h
-      ├── husky.sh
-      ├── pre-commit   (模板，非自定义)
-      ├── commit-msg   (模板，非自定义)
-      └── ...
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] .husky/ 目录存在
-- [x] .husky/_/ 包含 husky 模板文件
-- [x] package.json 包含 Husky 依赖
-- [x] package.json.scripts 包含 prepare: "husky install"
-- [x] `pnpm install` 时自动运行 prepare
-
-### Risks (风险)
-
-- ⚠️ **Husky 在某些环境不工作**
-  - 缓解: 未配置强制 hooks，工具可手动运行
-
----
-
-## Task Card 4: 配置 Pre-commit Hook（可选）
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A4-4
-Title: 配置 pre-commit hook 自动运行 lint 和 format
-Priority: LOW (OPTIONAL)
-Status: ⚠️ NOT IMPLEMENTED (Retrospective)
-Owner: ClaudeCode
-Estimate: 10 分钟
-Actual: 未实施
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- 自动在提交前运行 lint 和 format 检查
-- 防止不符合规范的代码进入仓库
-- 提高代码质量
-
-**Why Not (为什么未实施)**:
-- 任务定义标记为"可选"
-- 开发者可手动运行 lint/format
-- 避免强制自动化可能导致的开发阻碍
-
-**Input (输入)**:
-- Husky 已安装
-- lint 和 format scripts 已配置
-
-**Output (输出)**:
-- .husky/pre-commit 自定义脚本（未实施）
-
-### Implementation (实施)
-
-**Steps (如果实施的话)**:
-
-1. 创建 .husky/pre-commit 文件
-   ```bash
-   npx husky add .husky/pre-commit "pnpm lint"
-   npx husky add .husky/pre-commit "pnpm format:check"
-   ```
-
-2. （可选）使用 lint-staged 仅检查暂存文件
-   - 安装 lint-staged
-   - 配置 .lintstagedrc
-   - pre-commit 运行 lint-staged
-
-**Why Not Implemented (未实施原因)**:
-- 任务标记"可选"
-- 团队可能需要灵活性（不强制自动检查）
-- 可通过 CI/CD 补充检查
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [ ] .husky/pre-commit 自定义脚本存在
-- [ ] pre-commit 运行 lint 检查
-- [ ] pre-commit 运行 format 检查
-- [ ] （可选）使用 lint-staged 仅检查暂存文件
-- [ ] Git commit 触发自动检查
-
-**Status**: ❌ 未实施（任务可选）
-
-### Risks (风险)
-
-- ⚠️ **Pre-commit hook 可能阻碍快速提交**
-  - 缓解: 未实施，开发者手动控制
-
-- ⚠️ **Lint/format 失败阻止提交**
-  - 缓解: 未实施，避免强制
-
----
-
-## Summary (总结)
-
-### Completed Tasks (已完成任务)
-
-| TaskID | Title | Estimate | Actual | Status |
-|--------|-------|----------|--------|--------|
-| A4-1 | 配置 ESLint | 20 min | ~20 min | ✅ COMPLETED |
-| A4-2 | 配置 Prettier | 15 min | ~15 min | ✅ COMPLETED |
-| A4-3 | 安装 Husky | 10 min | ~10 min | ✅ COMPLETED |
-| A4-4 | 配置 pre-commit hook (可选) | 10 min | 未实施 | ⚠️ NOT IMPLEMENTED |
-| **Total** | | **55 min** | **~45 min** | **✅ 大部分完成** |
-
-### Deliverables (交付物)
-
-1. ✅ `.eslintrc.cjs`
-   - 29 行 CommonJS 配置
-   - TypeScript 解析器和规则
-   - Prettier 集成（避免冲突）
-
-2. ✅ `.prettierrc` + `.prettierignore`
-   - 10 行风格配置
-   - 8 行忽略规则
-
-3. ✅ `package.json`
-   - ESLint, Prettier, Husky 依赖
-   - lint, format, format:check, prepare scripts
-
-4. ✅ `.husky/` 目录
-   - Husky 已安装
-   - 模板文件存在
-
-5. ⚠️ `.husky/pre-commit`
-   - 未实施（任务可选）
-
-### Quality Metrics (质量指标)
-
-- **估算准确性**: 55 分钟估算 vs ~45 分钟实际（82% 准确，可选部分未实施）
-- **配置完整性**: ESLint + Prettier 完整，Husky 安装，hooks 未配置
-- **工具验证**: `pnpm lint` ✓, `pnpm format:check` ✓
-- **可选性**: 工具可手动运行，不强制自动化
-
----
-
-## Retrospective Notes (追溯说明)
-
-**Process Violation (流程违规)**:
-- ❌ 实际开发中跳过了 Align/Atomize/Approve 阶段
-- ❌ 直接进入 Automate 阶段开始配置 lint/format
-- ✅ 通过追溯补齐任务卡进行补救
-
-**Implementation Notes (实施说明)**:
-- ✅ A4-1, A4-2, A4-3 已完成
-- ⚠️ A4-4 未实施（任务定义为"可选"）
-- 工具可手动运行，符合"可选"要求
-
-**Lessons Learned (经验教训)**:
-1. "可选"任务可部分实施
-2. 配置 lint/format 比配置 hooks 更重要
-3. 追溯补齐可记录实际决策过程
-
-**Approval Required (需要批准)**:
-- ⏳ 等待用户批准本追溯性任务卡
-- ⏳ 用户批准后才能继续后续任务的 Review
-
----
-
-**注**: 本文档为追溯性创建，基于已完成的技术实现（配置文件）反推任务拆解。A4-1 到 A4-3 已实际完成，A4-4 未实施（任务可选），现等待用户批准追溯补齐的合理性。