diff --git a/docs/OPENSPEC.md b/docs/OPENSPEC.md index 0cf90ed..6c11136 100644 --- a/docs/OPENSPEC.md +++ b/docs/OPENSPEC.md @@ -1,7 +1,7 @@ # OpenSpec Global Standards | 全局开发规范 -**Version**: 1.1.0 -**Date**: 2025-11-21 +**Version**: 1.2.0 +**Date**: 2025-11-22 **Project**: Open Wisdom Lab Website **Status**: Living Document (活文档) @@ -9,6 +9,7 @@ ## 📋 Table of Contents +- [0. Documentation Architecture](#0-documentation-architecture) - [1. Introduction](#1-introduction) - [2. Architecture Standards](#2-architecture-standards) - [3. Code Organization](#3-code-organization) @@ -26,6 +27,49 @@ --- +## 0. Documentation Architecture + +### 0.1 文档职责划分 + +本项目有两个核心规范文档，各有侧重： + +| 文档 | 位置 | 目标读者 | 主要内容 | +|------|------|---------|----------| +| **CLAUDE.md** | `/CLAUDE.md` | AI 助手 (Claude Code) | 项目快速参考、开发命令、i18n 规范、代码审查清单 | +| **OPENSPEC.md** | `/docs/OPENSPEC.md` | 人类开发者 | 完整架构标准、代码规范、测试规范、部署流程 | + +### 0.2 避免重复维护 + +为避免信息不一致： + +1. **技术栈版本** - 以 `package.json` 为准，两文档引用时说明"详见 package.json" +2. **项目结构** - OPENSPEC.md 为权威源，CLAUDE.md 仅保留精简版本 +3. **i18n 规范** - 两文档均需保留（AI 助手高频使用），保持同步 +4. **组件开发规范** - OPENSPEC.md 为完整版，CLAUDE.md 保留快速参考 + +### 0.3 更新原则 + +- **新增规范** → 先更新 OPENSPEC.md，再同步简化版到 CLAUDE.md +- **版本变更** → 更新 package.json，两文档均添加"详见 package.json"引用 +- **审查变更** → 每次更新时检查两文档的一致性 + +### 0.4 相关文档索引 + +``` +docs/ +├── OPENSPEC.md # 本文档 - 全局开发规范 (权威源) +├── ROADMAP.md # 产品路线图与开发计划 +├── DESIGN_SYSTEM.md # 设计系统规范 +├── ARCHITECTURE.md # 系统架构说明 +├── DEPLOYMENT.md # 部署流程指南 +├── CONSISTENCY_AUDIT.md # 代码一致性审核 +├── CONTENT_GAPS.md # 内容缺口分析 +├── DEVELOPMENT.md # 开发环境搭建 +└── component-props-guide.md # 组件 Props 类型化指南 +``` + +--- + ## 1. Introduction ### 1.1 Purpose | 目的 @@ -1479,6 +1523,7 @@ import logo from '~/assets/images/logo.svg'; | Version | Date | Author | Changes | |---------|------|--------|---------| +| 1.2.0 | 2025-11-22 | Claude | 添加文档架构章节(Section 0)，明确 CLAUDE.md 与 OPENSPEC.md 职责划分 | | 1.1.0 | 2025-11-21 | Claude | 更新技术栈版本，同步 package.json | | 1.0.0 | 2025-11-19 | Claude | Initial OpenSpec creation | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 53bc9a6..894c21e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # Product Roadmap 2025-2026 | 产品路线图 -**Version**: 1.3.0 +**Version**: 1.4.0 **Last Updated**: 2025-11-22 **Project**: Open Wisdom Lab Website **Related Documents**: [docs/](./docs/) 目录下的所有文档 @@ -70,6 +70,7 @@ - [x] 移除 6 个未使用组件 (HighlightedPosts, LatestPosts, Button, Card, Pricing, Announcement) - [x] 优化 PageLayout 移除重复的背景动画组件 - [x] 补充 Note.astro 组件双语翻译 + - [x] 移除 9 个 cyber 组件的 'use client' 指令 (消除 sourcemap 警告) #### Week 3-4: TypeScript 迁移 - [x] 添加类型定义 @@ -77,15 +78,16 @@ - [x] 定义 `SiteConfig.ts` - [x] 定义 `BlogPost.ts` - [x] 定义 `Navigation.ts` -- [ ] 组件 Props 类型化 - - [ ] 为所有组件添加 `export interface Props` +- [x] 组件 Props 类型化 (部分完成) + - [x] 为核心 widgets 组件添加 Props (Hero, Vision, CallToAction) + - [ ] 为剩余 ~19 个组件添加 `export interface Props` - [ ] 配置重构 - [ ] 创建 `src/config/` 模块化配置 **Deliverables:** - [x] 完整的开发规范文档 -- [ ] 100% TypeScript 覆盖 -- [ ] 0 ESLint/TypeScript 错误 +- [ ] 100% TypeScript 覆盖 (~80% 已完成) +- [x] 0 ESLint/TypeScript 错误 (构建通过) - [x] 统一的代码风格 **Metrics:** @@ -758,6 +760,15 @@ Week 2: ## 📝 Changelog | 更新日志 +### Version 1.4.0 (2025-11-22) +- **文档架构优化** + - 更新 OPENSPEC.md v1.2.0: 添加文档架构章节(Section 0) + - 明确 CLAUDE.md 与 OPENSPEC.md 的职责划分和更新原则 +- **构建质量提升** + - 移除 9 个 cyber 组件的 'use client' 指令，消除 sourcemap 警告 + - 为核心组件添加 Props 类型定义 (Hero, Vision, CallToAction) +- **构建状态**: 0 errors, 0 warnings, 1 hint + ### Version 1.3.0 (2025-11-22) - **代码质量优化** - 修复 deprecated API (substr -> substring) diff --git a/src/components/ui/cyber/CyberButton.tsx b/src/components/ui/cyber/CyberButton.tsx index 7ee8116..40713de 100644 --- a/src/components/ui/cyber/CyberButton.tsx +++ b/src/components/ui/cyber/CyberButton.tsx @@ -1,5 +1,3 @@ -'use client'; - import React, { useRef, useState } from 'react'; import { motion, useMotionValue, useSpring } from 'framer-motion'; diff --git a/src/components/ui/cyber/CyberCard.tsx b/src/components/ui/cyber/CyberCard.tsx index 30b2598..d5a8249 100644 --- a/src/components/ui/cyber/CyberCard.tsx +++ b/src/components/ui/cyber/CyberCard.tsx @@ -1,5 +1,3 @@ -'use client'; - import React, { useRef, useState } from 'react'; import { motion, useMotionValue, useSpring, useTransform } from 'framer-motion'; diff --git a/src/components/ui/cyber/FloatingElements.tsx b/src/components/ui/cyber/FloatingElements.tsx index d07bcd7..5ca4405 100644 --- a/src/components/ui/cyber/FloatingElements.tsx +++ b/src/components/ui/cyber/FloatingElements.tsx @@ -1,5 +1,3 @@ -'use client'; - import React from 'react'; import { motion } from 'framer-motion'; diff --git a/src/components/ui/cyber/GlitchText.tsx b/src/components/ui/cyber/GlitchText.tsx index 34b4c42..8b5aec8 100644 --- a/src/components/ui/cyber/GlitchText.tsx +++ b/src/components/ui/cyber/GlitchText.tsx @@ -1,5 +1,3 @@ -'use client'; - import React, { useEffect, useState } from 'react'; import { motion } from 'framer-motion'; diff --git a/src/components/ui/cyber/GridBackground.tsx b/src/components/ui/cyber/GridBackground.tsx index 0a320ba..cf3f465 100644 --- a/src/components/ui/cyber/GridBackground.tsx +++ b/src/components/ui/cyber/GridBackground.tsx @@ -1,5 +1,3 @@ -'use client'; - import React from 'react'; import { motion } from 'framer-motion'; diff --git a/src/components/ui/cyber/HolographicBorder.tsx b/src/components/ui/cyber/HolographicBorder.tsx index 74e1b9d..5042b8a 100644 --- a/src/components/ui/cyber/HolographicBorder.tsx +++ b/src/components/ui/cyber/HolographicBorder.tsx @@ -1,5 +1,3 @@ -'use client'; - import React from 'react'; import { motion } from 'framer-motion'; diff --git a/src/components/ui/cyber/NoiseOverlay.tsx b/src/components/ui/cyber/NoiseOverlay.tsx index 5e2f694..4d41813 100644 --- a/src/components/ui/cyber/NoiseOverlay.tsx +++ b/src/components/ui/cyber/NoiseOverlay.tsx @@ -1,5 +1,3 @@ -'use client'; - import React from 'react'; interface NoiseOverlayProps { diff --git a/src/components/ui/cyber/ParallaxSection.tsx b/src/components/ui/cyber/ParallaxSection.tsx index f79f81f..eb29202 100644 --- a/src/components/ui/cyber/ParallaxSection.tsx +++ b/src/components/ui/cyber/ParallaxSection.tsx @@ -1,5 +1,3 @@ -'use client'; - import React, { useRef } from 'react'; import { motion, useScroll, useTransform, useSpring } from 'framer-motion'; diff --git a/src/components/ui/cyber/ScrollReveal.tsx b/src/components/ui/cyber/ScrollReveal.tsx index 3220e64..08c734c 100644 --- a/src/components/ui/cyber/ScrollReveal.tsx +++ b/src/components/ui/cyber/ScrollReveal.tsx @@ -1,5 +1,3 @@ -'use client'; - import React, { useRef } from 'react'; import { motion, useInView, type Variants } from 'framer-motion'; diff --git a/src/components/widgets/CallToAction.astro b/src/components/widgets/CallToAction.astro index cdd681d..23041bb 100644 --- a/src/components/widgets/CallToAction.astro +++ b/src/components/widgets/CallToAction.astro @@ -1,5 +1,23 @@ --- import { CyberButton } from '~/components/ui/cyber'; + +/** + * Call to Action component for conversion points + * + * @component + * @example + * ```astro + * + * ``` + */ +export interface Props { + /** Link destination for the CTA button @default '#contact' */ + href?: string; + /** Optional custom class name */ + class?: string; +} + +const { href = '#contact', class: _className = '' } = Astro.props; ---
@@ -22,7 +40,7 @@ import { CyberButton } from '~/components/ui/cyber';
联系我们 → @@ -33,7 +51,7 @@ import { CyberButton } from '~/components/ui/cyber';