diff --git a/.dockerignore b/.dockerignore index 932bbd6..6f56cd7 100644 --- a/.dockerignore +++ b/.dockerignore @@ -15,3 +15,4 @@ graphy/dist graphy/*.egg-info **/__pycache__ **/.pytest_cache +nex_design_system \ No newline at end of file diff --git a/.gitignore b/.gitignore index 441c3c6..b6b01c4 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,6 @@ backend/models # AI .gemini-clipboard/ .claude/ + +# Design +nex_design_system/ \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..140f221 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ +# NEX Design System — Agent Entry Rules (0.1.6) + +本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 `docs/`、`config/` 和 `templates/`。如果本文件被合并到项目根 `AGENTS.md`,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。 + +> **本仓库的实际安装路径**(NEX 0.1.6 随仓库置于 `nex_design_system/`,以下路径相对项目根): +> 规范 `nex_design_system/docs/`、配置模板 `nex_design_system/config/`、模板 `nex_design_system/templates/`。 +> 本文件即项目根 `AGENTS.md`,因此 §1 已改写为实际路径,不再使用失效的 `docs/…` 相对路径。 + +## 1. 开始任务前必须读取 + +1. `nex_design_system/docs/00-governance-and-adaptation.md` +2. `nex_design_system/docs/02-design-principles.md` +3. `nex_design_system/docs/03-design-tokens.md` +4. `nex_design_system/docs/04-layout-system.md` +5. `nex_design_system/docs/05-component-system.md` +6. `nex_design_system/docs/06-interaction-system.md` +7. `nex_design_system/docs/07-page-patterns.md` +8. `nex_design_system/docs/08-accessibility-responsive.md` +9. `nex_design_system/docs/09-agent-execution-rules.md` +10. `nex_design_system/docs/12-responsive-accessibility-quality.md` +11. `nex_design_system/docs/14-accessibility-platform-matrix.md` +12. 项目根目录 `nex.config.yaml`(如存在) +13. 项目级 UI/UX 规范。本项目当前没有独立的「项目设计 specification」文档, + 实际权威来源为:`frontend/src/styles/design-tokens.css`(Token)、 + `frontend/src/theme/antdTheme.ts`(antd 主题映射)、 + `docs/sdd/architecture/standards/nex-conformance-matrix.md`(符合性与例外)、 + `docs/sdd/architecture/standards/responsive-breakpoint-registry.md`(断点登记)、 + `docs/quickstart.md` §6(前端约定)。 + +只在任务涉及 NexDocus 历史实现或明确要求参考时,读取 +`nex_design_system/docs/01-project-audit.md`。它不是新项目的实施基线。 +NEX 0.1.6 包内**不含** `config/reference-nexdocus-profile.example.yaml` +(`nex_design_system/config/` 下只有 `project-profile.example.yaml`),引用该文件时按缺失处理。 + +## 2. 规范层级 + +遵循 NEX 三层模型: + +- **NEX Core**:跨项目质量与设计治理要求。 +- **Project Design Specification**:本项目视觉、布局、技术和交互的权威具体规范。 +- **Project Implementation**:当前主题、Token、组件和页面的真实实现。 + +NexDocus 参数、示例截图和示例组件名不是跨项目默认值。新项目的技术起步默认值以 `nex.config.yaml` 的 `stack` 为准;它只适用于新项目初始化,不是 NEX Core 对所有项目的强制技术栈。已有项目由项目级规范和真实实现决定。NEX Core 的通用 MUST 要求不能因项目偏好而取消,但可以采用不同技术方式满足。 + +## 3. 默认技术栈与自动发现(0.1.6;沿用 0.1.5 默认栈) + +`nex_design_system/config/project-profile.example.yaml` 是带有明确默认技术栈的配置模板。它不是“技术栈自动猜测模板”。 + +- **新项目**:`project.lifecycle` 为 `new`,或 `auto` 且仓库为空/没有实际应用代码时,必须把 `stack` 中的默认技术栈作为初始化目标。不得忽略这些选型,也不得再次要求用户填写一份技术栈问卷。 +- **已有项目**:`project.lifecycle` 为 `existing`,或 `auto` 且仓库已有应用代码/锁文件/构建配置时,以实际项目为准;默认技术栈仅供参考,不得据此替换、升级或迁移现有技术。 +- `project.type` 默认是 `fullstack`。纯前端或纯后端项目只需覆盖该字段。 +- 用户可以只覆盖 `stack` 中不符合当前项目意图的字段;未覆盖的默认值仍然有效。 + +新项目默认栈详见 `nex_design_system/docs/13-project-stack-defaults.md`,包括 React、TypeScript、Vite、Ant Design、Tailwind CSS v4、Python、FastAPI、SQLite/PostgreSQL 等。依赖版本采用创建时兼容的稳定版本,并提交 lockfile。 + +Agent 仍须自动发现已有项目的实际情况,包括: +- 项目名称、类型和主要界面语言; +- 前后端框架、语言、依赖版本、构建工具和 UI/样式方案; +- 项目 UI/UX 规范与设计决策文档; +- Token 权威来源、主题链路、共享组件目录和布局模式; +- 路由、断点、响应式规则、质量命令、视觉基线和 CI; +- 适用的辅助技术验证范围及尚未执行的人工测试。 + +无法发现的信息应标记 `UNKNOWN` 并说明证据缺口。不得把 `auto` 当成待用户填写的占位符,也不得为了补全配置而向用户发送长问卷。只有在信息无法从仓库确认且会影响产品选择、数据安全或高风险改动时,才提出最少量的具体问题。 + +新项目未覆盖的 `stack` 字段采用默认技术栈。已有项目不采用默认栈迁移,而是优先保留真实、成熟的现有实现;NEX 的通用设计质量要求仍然适用。 + +## 4. 开发前审计要求 + +修改既有前端前,先检查: + +- 项目技术栈和真实依赖(以锁文件、`package.json`、构建配置为证据)。 +- 项目级 UI 规范和设计决策记录。 +- Token 的单一事实来源及其派生链路(CSS、主题库、框架变量等)。 +- 已有组件、页面模式、主题机制和布局参数。 +- 现有交互路径、响应式行为、自动化检查与视觉基线。 + +将发现映射为 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED` 或 `NOT_APPLICABLE`。优先使用 `nex_design_system/templates/project-conformance-matrix.md`(本项目落地件:`docs/sdd/architecture/standards/nex-conformance-matrix.md`)。如果用户要求只审计,则不得修改业务代码。 + +## 5. 强制约束 + +1. **先盘点、后复用、再新增。** 先搜索项目现有共享组件和功能等价物。已有组件能满足需求时,不新增重复组件或第二套组件库。 +2. **项目适配优先。** 不将 NEX 参考项目的技术栈、品牌色、Token 名称、Header/Sider 尺寸、断点、控件高度或页面模式套用到其他项目。 +3. **不强制 `--nex-*` 命名。** 优先沿用项目现有语义 Token 和权威主题管线。只有项目没有合理命名体系、且批准采用 NEX 前缀时才可新增命名空间。 +4. **保持 Token 单一事实来源。** 可以由一个源文件/对象/配置单向派生 CSS Variables、组件库主题或框架变量;不得为同一语义值建立彼此独立、人工维护的多份来源。禁止为追求“统一”而破坏已经验证的单向派生链路。 +5. **保护成熟实现,但不固化缺陷。** 保留已验证的视觉和交互模式。若发现可复现的功能缺陷、安全问题或可访问性缺陷,应说明证据并提出最小修复;不得以“保持现状”为由忽略缺陷。 +6. **不擅自改变业务交互。** 视觉改造不得改变用户操作路径、数据语义、默认值或业务流程,除非任务明确授权。修复可访问性时应优先保持原操作意图和鼠标行为。 +7. **不擅自改技术栈。** 不升级框架、替换 UI 库、改变 JS/TS 方案或引入新样式系统,除非用户明确批准。 +8. **页面模式按需采用。** 只为项目真实存在的页面和工作区选择模式。`NOT_APPLICABLE` 的页面、组件和工作区不应被引入。 +9. **避免无意义封装。** 不机械包装所有第三方基础组件;只封装重复、高价值、需要统一 API/状态/可访问性行为的模式。 +10. **交互状态完整。** 适用时覆盖 loading、success、empty、error、disabled、permission-denied 等状态。状态不能只靠颜色表达。 +11. **可访问性是质量底线。** 自定义交互必须支持键盘、可见焦点和可访问名称;拖拽操作必须提供非拖拽替代路径。 +12. **滚动和尺寸必须基于实际布局。** 对嵌套 Flex/Grid 工作区检查 `min-width: 0`、`min-height: 0`、滚动容器归属和溢出,不要机械添加固定尺寸或 `overflow: hidden`。 +13. **不滥用局部覆盖。** 不用大量 `!important`、高优先级选择器或深层第三方 DOM 覆盖来修补应由 Token/主题/共享组件解决的问题;需要时说明范围和原因。 +14. **响应式断点必须登记。** 新增断点应有语义名称、数值/范围、布局理由、权威来源和边界测试;不得散落增加无法追踪的媒体查询。 +15. **窄屏数据必须可对账。** 隐藏列、卡片化或折叠详情不得导致重要数据无处可见;必须核验字段、记录数、顺序和动作仍可访问。 +16. **图标不得污染可访问名称。** 装饰性图标应从辅助技术名称计算中排除;图标与可见文案组合时避免重复朗读;图标本身不能以内部 glyph 名称充当业务文案。 +17. **真实 AT 验证按风险触发且跨平台选择。** 日常默认 E0–E2;只有复杂自定义控件、拖拽/排序、复合导航、关键数据表格、重要 Live Region 或合同/目标用户要求触发 E3。macOS 使用 VoiceOver,Windows 使用 NVDA(必要时 JAWS/Narrator),Linux 使用 Orca。E3 不适用时记录 `E3_NOT_REQUIRED`;必要但环境不可用时标记 `MANUAL_QA_REQUIRED`。 +18. **不得擅自启动屏幕阅读器。** 启动、关闭或切换 VoiceOver/NVDA/Orca 等系统 AT 前必须获得用户对本次 E3 的明确授权。记录初始状态,不得关闭用户原本启用的 AT,不得擅改系统级辅助功能设置。日常视觉、浏览器自动化和键盘验收不得启动屏幕阅读器。 +19. **样式层与性能优化必须有证据。** 不为形式一致进行全量 CSS Layer 迁移;不为消除 Bundle 警告盲目调阈值或分包。先提供级联冲突或实际加载数据,再做最小变更。 +20. **范围受控。** 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。 + +## 6. 标准工作流 + +1. 读取 NEX Core、项目配置和项目级设计规范。 +2. 检查真实实现并建立符合性/差异映射。 +3. 明确任务范围、复用组件、可能受影响页面和回归面。 +4. 对跨组件或跨页面改动先提交实施计划;仅在用户已明确授权的范围内执行。 +5. 先修正 Token/主题/共享模式,再迁移具体页面;避免一次性机械替换。 +6. 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。 +7. 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。 +8. 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。 +9. 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;E3 按风险触发,不适用时记录 `E3_NOT_REQUIRED`,必要但未执行时标记 `MANUAL_QA_REQUIRED`。 + +## 7. 例外记录 + +偏离 NEX Core 的 SHOULD 或采用不同项目实现时,记录:规则、状态(通常为 `ADAPTED` / `DEFERRED`)、原因、证据、影响范围、责任人/批准来源和复审条件。不得把单个项目的例外自动推广为全局规范。 + +## 8. 完成定义 + +只有在以下事项满足后,才能报告任务完成: + +- 项目规范与实现之间没有未说明的重大冲突。 +- 新增实现优先复用了现有组件、Token 和页面模式。 +- 没有未经授权改变技术栈、布局基线或业务交互。 +- 适用的主题、响应式、键盘和状态检查已执行。 +- 项目真实可用的质量门禁已执行;不可执行项已说明。 +- 文档、配置和代码行为保持一致。 diff --git a/FETCH_HEAD b/FETCH_HEAD new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md index b317bdf..4801c62 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ v1.0.0 · FastAPI + React 18 + MySQL 8 + Redis ### 前端 | 组件 | 选型 | | --- | --- | -| 框架 | React 18 + React Router v6 | +| 框架 | React 18(TypeScript,`strict`)+ React Router v6 | | 构建 | Vite 5(`manualChunks` 分包、全部路由 lazy 加载) | | UI | Ant Design 5 + 自研设计令牌(无 Tailwind / postcss) | | 状态 | Zustand + Axios 统一封装 | @@ -149,7 +149,8 @@ cp .env.example .env # 按注释修改密码/端口/存储路径 ## 🧪 开发与质量 ```bash -# 前端:静态检查与构建 +# 前端:类型检查、静态检查与构建 +cd frontend && npm run typecheck cd frontend && npm run lint && npm run build # 后端:pytest(用例较少,见发布报告 OI 清单) @@ -157,9 +158,11 @@ cd backend && ./venv/bin/pip install -r requirements-dev.txt cd backend && ./venv/bin/python -m pytest ``` -- 前端统一使用 `@/` 别名指向 `frontend/src`;新页面必须在 `App.jsx` 用 `lazy()` 注册。 -- 交互提示统一走 `components/Feedback` 的 `Toast`(`Toast.confirm` 替代 `Modal.confirm`)。 +- 前端为 TypeScript,统一使用 `@/` 别名指向 `frontend/src`;新页面必须在 `App.tsx` 用 `lazy()` 注册。 +- 交互提示统一走 `components/Toast/Toast` 的 `Toast`(`Toast.confirm` 替代 `Modal.confirm`);`components/Feedback` 是它依赖的 antd 桥接层。 - 颜色/圆角/间距一律取 `styles/design-tokens.css` 与 antd token,禁止硬编码色值。 +- 接口错误提示统一用 `utils/apiError` 取后端 `detail`;后端返回类型集中在 `types/api.ts`。 +- 质量门禁:`npm run typecheck`(Vite 构建不做类型检查)、`npm run lint`、`npm run build`。 - 数据库结构变更:改 `app/models/`,并在 `app/core/migrations.py` 增加幂等补列逻辑;**不要**再往仓库里追加一次性 `.sql`。 ## 🔒 安全要点 diff --git a/docs/quickstart.md b/docs/quickstart.md index 057fa35..330bb9a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -112,11 +112,31 @@ npm run dev ## 6. 前端约定 -- 开发端口 `5173`,`vite.config.js` 已把 `/api` 代理到 `http://localhost:8000`,因此**前端不需要配置后端地址**。 -- 路径别名 `@` → `frontend/src`。 -- 页面一律在 `src/App.jsx` 中用 `lazy()` 注册,路由级懒加载。 -- 主题/颜色取自 `src/styles/design-tokens.css` 与 `src/theme/antdTheme.js`,不要写死色值。 -- 全局提示统一 `@/components/Toast`(含 `Toast.confirm`),不要散用 `Modal.confirm` / `message.*`。 +- 前端为 **TypeScript**(`strict` + `noUnusedLocals` + `noUnusedParameters`),源码只有 `.ts` / `.tsx`。 +- 开发端口 `5173`,`vite.config.ts` 已把 `/api` 代理到 `http://localhost:8000`,因此**前端不需要配置后端地址**。 +- 路径别名 `@` → `frontend/src`(`tsconfig.json` 的 `paths` 与 Vite `resolve.alias` 保持一致)。 +- 页面一律在 `src/App.tsx` 中用 `lazy()` 注册,路由级懒加载。 +- 主题/颜色取自 `src/styles/design-tokens.css` 与 `src/theme/antdTheme.ts`(唯一 Token 源),不要写死色值。 +- 全局提示统一 `@/components/Toast/Toast`(含 `Toast.confirm`),不要散用 `Modal.confirm` / `message.*`。 +- 后端接口的请求/响应类型集中在 `src/types/api.ts`,新增接口时先补契约再写页面。 +- 接口错误取值统一走 `@/utils/apiError`(`getApiErrorDetail` / `getApiErrorMessage`),不要写 `error.response?.data?.detail`。 +- 用 `div`/`span` 承载点击时,必须用 `@/utils/a11yActivation` 的 `keyboardActivation()` 补 `role`/`tabIndex`/`onKeyDown`, + 并给控件可访问名称(`aria-label` 或可见文案);优先直接用原生 ` )} diff --git a/frontend/src/components/ListTable/ListTable.jsx b/frontend/src/components/ListTable/ListTable.tsx similarity index 51% rename from frontend/src/components/ListTable/ListTable.jsx rename to frontend/src/components/ListTable/ListTable.tsx index 77dd322..fbd1b18 100644 --- a/frontend/src/components/ListTable/ListTable.jsx +++ b/frontend/src/components/ListTable/ListTable.tsx @@ -1,29 +1,45 @@ -import { Table } from 'antd' +import type { Key, ReactElement, ReactNode } from 'react' +import { cloneElement, isValidElement } from 'react' +import { Table, type TablePaginationConfig } from 'antd' +import type { ColumnsType } from 'antd/es/table' +import { namePageItem } from '@/utils/antdA11y' import './ListTable.css' +interface ListTableScroll { + x?: number | string | true + y?: number | string +} + +interface ListTableProps { + columns: ColumnsType + dataSource: RecordType[] + /** 行唯一标识字段 */ + rowKey: Extract + /** 选中的行 */ + selectedRowKeys?: Key[] + onSelectionChange?: (selectedRowKeys: Key[]) => void + /** 是否跨页全选所有数据 */ + isAllPagesSelected?: boolean + /** 总数据量(用于跨页全选) */ + totalCount?: number + onSelectAllPages?: () => void + onClearSelection?: () => void + pagination?: TablePaginationConfig | false + scroll?: ListTableScroll + onRowClick?: (record: RecordType) => void + /** 当前选中的行 */ + selectedRow?: RecordType | null + loading?: boolean + className?: string +} + /** - * 列表表格组件 - * @param {Object} props - * @param {Array} props.columns - 表格列配置 - * @param {Array} props.dataSource - 数据源 - * @param {string} props.rowKey - 行唯一标识字段 - * @param {Array} props.selectedRowKeys - 选中的行 - * @param {Function} props.onSelectionChange - 选择变化回调 - * @param {boolean} props.isAllPagesSelected - 是否跨页全选所有数据 - * @param {number} props.totalCount - 总数据量(用于跨页全选) - * @param {Function} props.onSelectAllPages - 选择所有页回调 - * @param {Function} props.onClearSelection - 清除选择回调 - * @param {Object} props.pagination - 分页配置 - * @param {Object} props.scroll - 表格滚动配置 - * @param {Function} props.onRowClick - 行点击回调 - * @param {Object} props.selectedRow - 当前选中的行 - * @param {boolean} props.loading - 加载状态 - * @param {string} props.className - 自定义类名 + * 列表表格组件:统一表格 + 分页 + 行选择(含跨页全选)的展示与文案。 */ -function ListTable({ +function ListTable({ columns, dataSource, - rowKey = 'id', + rowKey, selectedRowKeys = [], onSelectionChange, isAllPagesSelected = false, @@ -35,26 +51,32 @@ function ListTable({ showSizeChanger: true, showQuickJumper: true, }, - scroll = { x: 1200}, + scroll = { x: 1200 }, onRowClick, selectedRow, loading = false, className = '', -}) { +}: ListTableProps) { // 行选择配置 const rowSelection = { selectedRowKeys, - onChange: (newSelectedRowKeys) => { + onChange: (newSelectedRowKeys: Key[]) => { onSelectionChange?.(newSelectedRowKeys) }, // 当跨页全选时,禁用单个复选框 getCheckboxProps: () => ({ disabled: isAllPagesSelected, }), + // antd 把行复选框包在内容为空的 `