Feature Docs

功能文档索引（Feature Docs Index）

触发条件

当用户提到以下内容时使用：

• "功能文档"、"feature docs"、"功能设计"、"feature design"
• "查看 listing/商品/钱包/配送/主题/i18n/账号绑定/settings 的设计文档"
• "这个模块是怎么设计的"
• 开发新功能或修改现有功能时需要了解设计背景

概述

docs/features/ 目录下维护着各核心模块的详细设计文档，包含架构设计、数据结构、API 接口、组件清单、i18n 键、迁移状态等信息。开发前应先查阅相关文档，确保实现与整体设计一致。

文档索引

核心功能模块

基础设施模块

元文件

使用指南

1. 开发新功能前

1. 检查 docs/features/ 是否有对应文档
2. 有 → 阅读文档，了解架构设计和已有实现
3. 无 → 使用 _template.md 创建新文档，在开发完成后补充

2. 修改现有功能时

1. 阅读对应的 feature doc，确认修改不偏离设计意图
2. 完成修改后，同步更新文档中的：
   - 文件路径（如有新增/移动）
   - 数据结构（如有字段变更）
   - API 接口（如有新增/修改）
   - 迁移状态（如有进展）
   - 版本号和更新日期

3. 文档与 Skill 的关系

Feature docs 提供模块级详细设计（具体到文件路径、数据结构、API 端点），而 Skills 提供跨模块开发规范（如代码风格、组件开发模式、安全实践）。两者互补：

• Feature docs → "这个模块怎么实现的，涉及哪些文件"
• Skills → "实现时应遵循什么规范和最佳实践"

4. 创建新文档

使用模板 docs/features/_template.md，确保包含：

• 功能 ID、版本、状态
• 架构设计和数据流
• 核心文件路径清单
• 关键数据结构
• API 接口
• i18n 翻译键
• 迁移检查清单

各文档关键信息速查

listing-module.md 要点

• 核心 Hook: packages/core/hooks/useListingForm.ts（表单状态、验证、提交）
• 商品类型: PHYSICAL_GOOD、DIGITAL_GOOD、SERVICE、RWA_TOKEN、CRYPTOCURRENCY
• 页面: apps/web/src/app/listing/new/page.tsx 和 edit/[slug]/page.tsx
• 注意: buildRequestData() 是 useListingForm 内部函数，不对外暴露

shipping-profiles.md 要点

• 类型定义: packages/core/types/shippingConfig.ts（不是 shipping.ts）
• 核心 Hook: packages/core/hooks/useShippingProfiles.ts
• 组件目录: apps/web/src/components/Shipping/（12 个组件）
• 后端: Protobuf 定义在 pkg/orders/mbzpb/listing.proto

wallet-integration.md 要点

• 核心 Hook: packages/core/hooks/useWallet.ts（基于 AppKit）
• 服务目录: packages/core/services/payment/（不是 wallet/）
• Escrow: 独立在 escrow.ts，不在 useWallet 中
• Provider: 必须在 AppKitProvider 内使用

account-binding.md 要点

• 服务: packages/core/services/auth/accountBinding.ts
• 支持的 OAuth: Discord、Telegram、Google、GitHub、Apple、WeChat
• 认证中心: Casdoor

i18n.md 要点

• 核心 Hook: packages/core/hooks/useI18n.ts
• 翻译文件: packages/core/i18n/locales/{en,zh,ja,ko,es,fr,de,ru,pt}.ts
• 额外导出: language/setLanguage（locale 别名）、supportedLocales、localeInfo

theme-system.md 要点

• 核心模块: packages/core/theme/（types.ts, themes.ts, useTheme.ts）
• 6 种主题: classic, crypto, business, cyberpunk, nature, luxury
• 防闪烁: 内联脚本在 layout.tsx 中

ui-components.md 要点

• shadcn/ui: apps/web/src/components/ui/（20+ 组件）
• 自定义组件: @mobazha/ui 包
• 导入: import { Button } from '@/components/ui'

PG-201_STORE_BRANDING_DESIGN.md 要点

• 核心类型: packages/core/types/storeConfig.ts（Discriminated Union，StoreSection 严格绑定 Props）
• 渲染引擎: apps/web/src/components/store-sections/SectionRenderer.tsx（Server Component，SSR）
• 主题提供者: apps/web/src/components/store-sections/StoreThemeProvider.tsx（WCAG AA 对比度安全）
• Admin 编辑器: apps/web/src/components/store-editor/（拖拽排序、调色板、实时预览）
• 后端 API: GET/PUT /v1/settings/storefront (owner) + GET /v1/settings/storefront/{peerID} (public)
• 存储: NodeSettings key-value（key=store_config）
• 注意: RichTextSection 必须是 'use client'（DOMPurify 需要 DOM）
• 注意: store-tabs 是系统级 Section，不可删除，只可排序和隐藏
• 工作分支: feature/pg-tier2-branding | Worktree: mobazha-unified-tier2

settings-redesign.md 要点

• 核心变更: 从 SettingsDrawer 弹框模式迁移到 /settings/* 页面路由模式
• 布局: Shopify Settings Layout — SettingsSection 组件，左列描述(2fr) + 右列表单卡片(5fr)
• 组件目录: apps/web/src/components/SettingsContent/（各 Section 的内容组件）
• 布局组件: apps/web/src/components/SettingsLayout/（SettingsSection, SaveBar, PageHeader）
• Hooks: packages/core/hooks/use{Section}Settings.ts（每个 Section 的业务逻辑）
• 5 Phase 改造: P0 基础组件 → P1 General 样板 → P2 全部迁移 → P3 切换入口+清理 → P4 打磨 → P5 AI
• Cursor Rule: .cursor/rules/settings-redesign.mdc（改动 settings 文件时自动应用）
• 禁止: 在 SettingsDrawer 中新增功能、使用 openSettings() 弹框