386f1345c3
- 添加项目配置文件：.vercelignore、.codex/config.toml、postcss.config.js、.prettierrc 等 - 设置构建工具链：Vite + React + TypeScript + TailwindCSS - 添加核心组件：HeaderBar、TierRow、ItemCard、Pool - 配置 CI/CD 和部署相关文件：vercel.json、DEPLOY.md - 添加开发工具配置：ESLint、Prettier、EditorConfig - 实现基础功能：拖拽排序、图片处理、状态管理
54 lines
3.8 KiB
Markdown
54 lines
3.8 KiB
Markdown
<!--
|
||
同步影响报告
|
||
- 版本变更：1.0.0 → 1.0.1
|
||
- 修改的原则：全量翻译（极致体验与可访问性；统一设计系统与视觉一致性；React + 类型安全栈纪律；精益质量闸门；构建与文档纪律）
|
||
- 新增章节：无
|
||
- 移除章节：无
|
||
- 模板更新：✅ .specify/templates/plan-template.md; ✅ .specify/templates/tasks-template.md
|
||
- 后续待办：无
|
||
-->
|
||
|
||
# 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
|