# Toolkit 宪章 ## 核心原则 ### 极致体验与可访问性 - 公共工具和管理端都必须提供精致、响应迅速的体验，具备键盘可达性、焦点状态和 WCAG AA 对比度；主要页面首屏加载需控制在感知快速的范围（参考宽带环境 <2s）。 - 理由：平滑可信的交互让用户在工具目录与管理控制中保持高效。 ### 统一设计系统与视觉一致性 - 仅使用一套 Tailwind + shadcn/ui 设计系统，公域与管理端共享；统一定义色彩、间距、排版、圆角等设计令牌，复用组件而非临时样式。 - 理由：一致性降低维护成本，保持两端优雅且同源。 ### React + 类型安全栈纪律 - 前台与后台必须基于 React + TypeScript + Vite；严格类型覆盖 API 契约与组件 props，构建链路统一并提交 ESLint/Prettier 配置。 - 理由：单一且类型安全的栈能加速交付并减少回归。 ### 精益质量闸门 - 在 CI 中运行 lint/format 并作为合并闸门；仅为关键路径（核心工具调用、计费/角色、设计系统回归）添加测试，避免泛滥覆盖；优先集成或组件交互测试而非重复的碎片单测。 - 理由：聚焦价值的覆盖保持质量，同时不浪费时间在低收益测试上。 ### 构建与文档纪律 - 提供 Makefile 目标（`make init|lint|test|dev|clean`），构建产物仅落在 `build/` 或 `dist/`；新模块需附简短 README 说明职责、入口与依赖；环境变量放在 `.env.example`。 - 理由：可预期的命令与轻量文档让上手与维护更高效。 ## 技术与结构约束 - 仓库结构：`src/` 核心代码，`tests/` 定向测试，`scripts/` 自动化，`docs/` 设计与决策，`assets/` 静态/示例，`tmp/`（忽略）用于本地输出；构建产物只发布到 `build/` 或 `dist/`。 - 公域与管理端共用基础样式、主题与工具函数，避免引入其他框架或 CSS 体系造成分裂。 - 配置需入库（如 `.editorconfig`、ESLint/Prettier/Tailwind），使用 UTF-8、LF、2 空格缩进（若工具强制则显式声明）。 - 禁止提交密钥；提供 `.env.example`，并在 README 或模块文档说明变量用途。 ## 流程与评审 - 功能工作以规范和实施计划为起点，并引用本宪章；计划须通过 Constitution Check 后再进入调研/实现。 - 任务按用户故事组织，只在规格要求或关键路径需要时加入测试；避免填充性任务与冗余覆盖。 - 代码评审需核验设计系统复用、技术栈一致性、lint/format 闸门、Makefile 命令与文档要求。 - 发布或演示前必须验证体验精致度（视觉一致性、可访问性行为）及栈合规性（React+TS+Vite，Tailwind/shadcn 使用）。 ## 治理 - 本宪章优先于仓库内其他前端/管理端实践文档；偏离需在实施计划与 PR 中明示并获批准。 - 修订需包含：拟议文本、动机、影响评估及模板同步；版本遵循语义化：MAJOR（破坏性变更/移除原则）、MINOR（新增原则或扩展章节）、PATCH（澄清或措辞优化）。 - 在计划评审与 PR 评审中执行合规检查；若存在偏离，需在计划/任务的 Complexity Tracking 中记录原因与缓解。 - 宪章与模板存于仓库；运行时指导应放在 README/文档，并在规格与计划中链接，确保贡献者一致。 **Version**: 1.0.1 | **Ratified**: 2025-12-11 | **Last Amended**: 2025-12-11