sakibcc/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add frontend development guidelines and structure documentation

Browse Source 
- Introduced API guidelines for interface contracts and request handling.
- Added design tokens usage guidelines for consistent styling across the project.
- Established DTO guidelines for defining request parameters and response data types.
- Created frontend structure guidelines to clarify directory organization and code placement rules.
- Compiled a comprehensive frontend development guideline document covering various aspects of the development process.
- Implemented quality guidelines to ensure code maintainability and adherence to best practices.
This commit is contained in:
yuxuanhui
2026-07-25 22:20:25 +08:00
commit 91861565bb
78 changed files with 5001 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AI Coding/inbox/20260625-central-compounding-brain.md
+52
View File
@@ -0,0 +1,52 @@
---
id: 20260625-central-compounding-brain
title: 使用中央知识仓库管理跨项目 AI coding 经验
created: 2026-06-25
updated: 2026-06-25
status: candidate
scope: global
category: agent-workflows
confidence: medium
last_verified: 2026-06-25
promotion_target: skill
projects:
- personal-codex
tags:
- compound-engineering
- knowledge-management
- cross-project
---
# 使用中央知识仓库管理跨项目 AI coding 经验
## Trigger
多个项目分别积累 AI coding 经验，导致相同纠正、失败路径和成功模式难以跨项目检索与复用。
## Context
当前 Obsidian Vault 被选为个人跨项目复利仓库。全局 Skill 负责工作流，Vault 负责持续增长的经验数据，各项目继续保留与代码版本强关联的执行规则。
## Evidence
- 2026-06-25：确定采用中央大脑与项目执行层分离的架构。
- 全局 Skill 位于 `~/.agents/skills/compound-coding/`。
- 中央知识入口位于 `AI Coding/index.md`。
## Root cause
经验如果只保留在单次对话或单个项目中，就无法稳定跨项目检索；如果所有规则都集中在全局提示中，又会造成上下文膨胀并污染项目边界。
## Preferred action
将新经验先写入中央 `inbox/`，验证后进入 `learnings/`，跨项目成立后再归纳为 `patterns/`。把确定性要求同步为项目测试、lint、hook、脚本或 `AGENTS.md`。
## Boundaries
- 项目专属架构、命令和业务事实仍以项目仓库为准。
- 中央经验在使用前需要根据当前代码和文档重新验证。
- 不把凭证、客户数据或其他敏感信息写入复利仓库。
## Promotion record
- 2026-06-25：创建全局 `compound-coding` Skill 作为工作流执行层；候选经验仍需经过实际项目使用验证。
AI Coding/inbox/20260627-cloud-runtime-project-root.md
+75
View File
@@ -0,0 +1,75 @@
---
id: 20260627-cloud-runtime-project-root
title: 云端运行时不要依赖 process.cwd() 推断项目根目录
created: 2026-06-27
updated: 2026-06-27
status: candidate
scope: global
category: debugging
confidence: high
last_verified: 2026-06-27
promotion_target: none
projects:
- evaluator-agent
tags:
- cloud-deployment
- path-resolution
- playwright
- diagnostics
---
# 云端运行时不要依赖 process.cwd() 推断项目根目录
## Trigger
本地测试能读到配置或资源，但部署到云端后同一流程表现为配置缺失、鉴权未执行、文件不存在、资源路径 404，且日志里只看到后续业务失败。
## Context
一次 Playwright 云端测试排查中，测试进程能访问目标页面，但前置鉴权没有执行，页面最终停留在登录页。最初怀疑是 cookie/sessionStorage 写入失败、Chrome 限制或跨域问题。后来通过运行时证据确认：fixture 已经执行，但没有读到项目 auth 配置。
关键差异是云端 Playwright 进程的 `process.cwd()` 是应用包目录，而项目文件和 `.evaluator/projects/<id>.json` 在另一个工作目录。代码用 `process.cwd()` 推断项目根目录，导致读取了错误位置的配置文件。
## Evidence
- 2026-06-26/27，`evaluator-agent` 云端测试排查。
- 运行时 `auth-setup` 证据显示：`projectIdPresent=true`，但 `authConfigured=false`，`authApplied=false`。
- 临时深度诊断曾显示运行时尝试读取 `/app/.evaluator/projects/<project-id>.json`，但实际项目产物位于 `/workspace/project/...`。
- 修复提交：`ee1e9b0 Fix Playwright project root resolution for auth config`。
- 相关文件：
- `packages/core/src/evaluator/run.ts`：启动 Playwright 时传入 `EVALUATOR_PROJECT_ROOT=projectRoot`。
- `packages/playwright/src/fixtures/ai-test.ts`：fixture 读取配置时使用 `EVALUATOR_PROJECT_ROOT || process.cwd()`。
- `.trellis/spec/frontend/run-analysis-contracts.md`：记录云端 cwd 与项目根目录可能不同的契约。
- 清理提交：`8547bd1 chore: remove temporary auth debug diagnostics`，保留稳定布尔证据，删除过细路径/配置探测字段。
## Root cause
已验证原因：云端运行进程的 cwd 不等于项目根目录。配置读取逻辑把 `process.cwd()` 当作项目根，导致读取错误路径，表现为配置不存在。
推断：类似问题也可能发生在测试报告、静态资源、项目级配置、凭证文件、生成产物、fixture 初始化、CLI 子进程中，只要代码通过 cwd 隐式推导项目根。
## Preferred action
对需要部署到云端或由子进程执行的代码：
1. 显式传递项目根目录，例如 `PROJECT_ROOT` / `EVALUATOR_PROJECT_ROOT`，而不是在下游模块里直接信任 `process.cwd()`。
2. 子进程启动处负责设置这个 env；fixture、worker、CLI helper 只读取显式根目录并保留 `process.cwd()` 作为本地直跑 fallback。
3. 在运行产物里记录低风险、结构化的健康检查字段，例如 `projectIdPresent`、`authConfigured`、`authApplied`，用于远程确认流程是否执行。
4. 临时深度诊断可以短期记录路径、config existence 等字段定位问题，但修复后应清理，避免长期暴露内部部署结构。
5. 把这个约束写成项目契约或测试，防止以后又退回 cwd 推断。
## Boundaries
- 本地单进程脚本、一次性维护脚本、明确从仓库根执行的工具可以使用 `process.cwd()`，但要把这个前提写清楚。
- 不要把密码、token、cookie 值、请求 body/header 值写入诊断产物。
- 路径诊断是否保留要看用户场景：短期排查可以详细，长期产品化证据应收敛到必要布尔状态和可操作错误摘要。
## Failed approaches
- 先排查 cookie/sessionStorage、CORS、Chrome flags 和页面 JS 错误，虽然有价值，但没有直接回答“fixture 是否读到配置”。
- 临时把 `configPath`、`configFilePresent`、`projectRoot` 等字段加入运行时证据能快速定位问题，但不适合作为长期默认产物。
- 不推荐把配置复制到云端 cwd 对应目录；这会形成两份配置，后续 UI、测试和服务端可能读到不同来源。
## Promotion record
- Not promoted.
AI Coding/inbox/20260715-codegraph-before-impact-analysis.md
+63
View File
@@ -0,0 +1,63 @@
---
id: 20260715-codegraph-before-impact-analysis
title: 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
created: 2026-07-15
updated: 2026-07-15
status: candidate
scope: global
category: agent-workflows
confidence: medium
last_verified: 2026-07-15
promotion_target: none
projects:
- oppein-react-component
tags:
- codegraph
- impact-analysis
- dependency-context
- agent-workflows
---
# 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
## Trigger
项目启用了 CodeGraph，且任务涉及跨包、跨目录或跨组件理解，调用链排查，重构、重命名、删除，或修改共享 API、类型、导出、hooks、服务接口和工具；也适用于需要评估回归范围或应补充哪些测试的任务。
## Context
当前项目的执行提示词将 CodeGraph 定位为影响分析的第一层上下文：先用代码关系索引缩小依赖范围，再回到源码、构建配置和精确文本核验，修改共享代码后再检查受影响文件和测试。这个流程既避免在陌生功能区盲目通读，也避免把图谱结果误当成完整事实。
## Evidence
- 2026-07-15：用户要求将当前项目的 CodeGraph 使用提示词沉淀到复利工程。
- `oppein-react-component/AGENTS.md:23-58`：记录了 CodeGraph 的触发条件、`status`/`sync` 规则、`explore`/`query`/`node`/`impact`/`callers`/`callees`/`affected` 的选择，以及源码核验和常规质量验证边界。
- 当前项目存在 `.codegraph/` 本地代码关系索引；该提示词明确要求首次使用时先检查索引状态。
## Root cause
已验证：代码关系图适合发现静态依赖、调用方和潜在影响范围，但不能可靠覆盖动态路径、字符串引用、构建配置和实现细节；索引过期时，图谱结论也可能失真。因此图谱只能用于缩小范围，不能单独证明“没有调用方”或“没有影响”。
推断：把 CodeGraph 放在影响分析前段，并固定接上源码核验与变更后测试范围检查，可以减少漏查共享调用方和遗漏回归测试的风险。
## Preferred action
1. 任务首次需要 CodeGraph 时先运行 `codegraph status`；仅在索引不是最新时运行 `codegraph sync`。不要自行执行 `init`、`index` 或 `uninit`，除非用户明确要求，或索引缺失且无法继续完成任务。
2. 按问题选择最小工具链：陌生模块用 `codegraph explore "<需求或模块>"`；查定义用 `codegraph query "<符号>"`，再用 `codegraph node "<符号>"` 阅读实现和调用链；修改共享 API 前用 `codegraph impact "<符号>"`，必要时补充 `callers` 和 `callees`。
3. 以图谱结果缩小源码阅读和搜索范围；修改前直接阅读相关实现，并用 `rg` 核对动态路径、字符串引用、构建配置和精确文本。
4. 共享代码修改完成后运行 `codegraph sync`，再用 `codegraph affected <改动文件>` 找出需要补充或执行的测试，最后仍按项目约定执行 lint、类型检查、构建和针对性测试。
## Boundaries
- 只有在项目启用 CodeGraph 且索引或对应 MCP 工具可用时，才直接套用这些命令；其他项目需先确认其工具和命令语义。
- 用户已指定文件和行，且只是局部文案、注释、格式或显然不影响外部行为的小改动，以及单文件、无公共接口变化的机械性修复，可以跳过 CodeGraph。
- CodeGraph 不能替代源码核验、`rg` 搜索、lint、类型检查、构建或测试；不要仅凭图谱结果断言不存在调用方或影响。
## Failed approaches
- 只依据图谱结果判断影响范围，会遗漏动态引用、配置驱动路径和未被索引覆盖的文本关系。
- 直接执行 `sync`、`init` 或 `index` 而不先检查状态，会增加不必要的索引操作，并可能偏离项目约定。
## Promotion record
- Not promoted. 当前只有 `oppein-react-component` 的一份项目证据；待在另一项目或独立场景复用并验证后，再考虑提升为全局 guidance、skill 或可执行检查。
AI Coding/inbox/20260724-bounded-list-flex-height-chain.md
+107
View File
@@ -0,0 +1,107 @@
---
id: 20260724-bounded-list-flex-height-chain
title: 有界列表页使用连续 Flex 高度链并收敛滚动视口
created: 2026-07-24
updated: 2026-07-24
status: candidate
scope: global
category: frontend-layout
confidence: medium
last_verified: 2026-07-24
promotion_target: none
projects:
- usercenter-react
tags:
- flex-layout
- min-height-zero
- bounded-workspace
- scroll-ownership
- data-table
---
# 有界列表页使用连续 Flex 高度链并收敛滚动视口
## Trigger
列表页、主从工作台或树表页面需要填满应用内容区，同时保持标题、筛选、操作栏和分页可见，只让表格数据区、树节点区或详情正文滚动；或者当前页面出现双滚动条、分页被挤出视口、`h-full` 不生效、窗口高度变化后布局失效。
## Context
`usercenter-react` 的商场管理页面曾需要移除固定像素高度推算，使应用外壳、路由页面、Tabs、组织树和数据表形成连续的有界高度链。修复后，普通内容页仍由共享 `<main>` 滚动，有界工作台则填满 `<main>` 并把滚动交给最小内容视口。
这项经验的核心不是“给页面加 `flex-col`”，而是同时解决两个契约：高度从视口向后代连续传递，滚动权从外层收敛到最小内容区域。任一中间层缺少明确高度或 `min-h-0`，后代的 `h-full`、`flex-1` 和 `overflow-auto` 都可能无法按预期工作。
## Evidence
- 2026-07-24：重新检查 `usercenter-react` 当前源码、项目规范和 Git 历史；中央经验库搜索“有界列表页 / 连续 Flex 高度链 / min-h-0 / 滚动视口”无重叠条目。
- `usercenter-react/src/shared/layout/app-layout.tsx:207-236`：应用根节点使用 `h-dvh overflow-hidden`，内容列使用 `flex h-full min-h-0 flex-col`，共享 `<main>` 使用 `min-h-0 flex-1 overflow-y-auto`。
- `usercenter-react/src/features/market-management/pages/market-management-page.tsx:181-230`：有界路由根节点、分栏、Tabs 和 TabPane 连续使用 `h-full`、`flex-1`、`min-h-0` 与受控 overflow。
- `usercenter-react/src/shared/table/data-table.tsx:40-45,168-232`：`fillHeight` 以 opt-in 方式把表格面板变成有界 Flex 列，工具栏和分页留在滚动视口之外，数据区域消费剩余高度。
- `usercenter-react/.trellis/spec/frontend/layout-guidelines.md:23-32,74-125`：记录了各布局边界的类契约、滚动归属、错误矩阵和禁止使用固定 `calc(100vh - Npx)` 的规则。
- `usercenter-react/specs/page-layout.spec.md:5-11`：产品级规范要求有界页面使用连续 Flex 高度链，并将 overflow 委托给最小树或数据视口。
- Git 提交 `ccf068c` 修复商场管理页面高度适配，`1bb14e8` 将实践整理为 bounded layout 指南，`849219a` 继续补充可伸缩侧栏场景下的表格滚动与 sticky 边界。
- 当前仓库的 `src/shared/list-templates/master-detail-list-template.tsx:34-60` 仍存在 `calc(100vh - 10.5rem)` 实现；这是需要结合响应式父级契约进一步验证的现有反例，不能仅凭规则直接判定或修改。
## Root cause
已验证：
- `flex-col` 和 `flex-1` 只负责空间分配，不会自动建立可解析的高度边界。
- Flex/Grid 子项默认的 `min-height: auto` 会阻止内容区域收缩；中间层缺少 `min-h-0` 时，内容会撑高页面而不是在指定视口内滚动。
- `h-full` 依赖祖先提供确定高度；高度链中断时，百分比高度不能可靠地代表剩余视口空间。
- 页面、共享 `<main>` 和表格数据区同时拥有纵向 overflow 时，会形成嵌套或竞争滚动条。
- `calc(100vh - Npx)`、JavaScript 测量和重复的标题高度常量容易在工具栏换行、外壳调整、缩放或窄屏布局下失效。
推断：把布局评审固定为“先从外向内检查高度链，再从内向外确认唯一滚动所有者”，比逐个添加高度类或 overflow 类更容易定位缺失环节，也更适合跨组件复用。
## Preferred action
1. 先区分页面模式：普通内容页继续由应用 `<main>` 滚动；只有需要固定控制区和内部滚动的页面才进入有界模式。
2. 从视口向目标滚动区域建立连续高度链：应用根节点建立动态视口边界，中间内容列使用 `flex h-full min-h-0 flex-col`，有界路由根节点使用 `flex h-full min-h-0 flex-col overflow-hidden`。
3. 为所有需要消费剩余高度或继续向下传递高度的 Flex/Grid 中间层添加 `min-h-0`；不要只修改最终表格容器。
4. 标题、筛选、操作栏、Tabs 头部和分页等固定区域使用 `shrink-0`。剩余内容区域使用 `min-h-0 flex-1`。
5. 将纵向滚动交给最小内容视口：通常是表格数据区、树节点区或详情正文。结构层使用 `overflow-hidden`，实际内容视口使用 `overflow-auto` 或 `overflow-y-auto`。
6. 共享表格的填高能力保持 opt-in；只有父级已经提供有界 `h-full/min-h-0` 区域时才启用，避免改变普通内容型页面的默认行为。
7. 优先使用 Flex 剩余空间，不使用固定 `calc(100vh - Npx)`、JavaScript 高度测量或跨组件共享的像素常量。
8. 在真实浏览器中验证滚动归属：有界页面不增加 body 高度，固定控制区和分页保持可见，只有目标数据区滚动；同时检查窄屏、工具栏换行、loading、empty 和 error 状态。类型检查、lint 和构建不能替代这项验证。
## Examples
```tsx
<div className="h-dvh overflow-hidden">
<div className="flex h-full min-h-0 flex-col">
<main className="min-h-0 flex-1 overflow-y-auto">
<section className="flex h-full min-h-0 flex-col overflow-hidden">
<header className="shrink-0">{header}</header>
<div className="shrink-0">{filtersAndActions}</div>
<div className="min-h-0 flex-1 overflow-hidden">
<DataTable fillHeight {...tableProps} />
</div>
</section>
</main>
</div>
</div>
```
记忆方式：高度从外向内连续传递，滚动权收敛到最小内容视口。
## Boundaries
- 普通详情页、表单页和自然增长的长页面通常应继续由共享 `<main>` 滚动，不要为了统一外观强制启用有界模式。
- 移动端主从区域改为纵向堆叠时，可能更适合自然页面滚动；有界模式可以只在桌面断点启用。
- `overflow-hidden` 只有在后代明确拥有滚动视口时才安全，否则会直接裁切内容。
- Tabs、Drawer、Spin、Table 和虚拟列表等第三方组件可能插入包装层，需要根据实际 DOM 补齐高度链或沿用组件自己的滚动机制。
- 可交互变宽的分栏可能触发第三方表格的 ResizeObserver 和 sticky 行为；`nativeStickyHeader`、固定列实现等属于组件或项目特例，不是连续 Flex 高度链的通用要求。
- 已存在的 `calc(100vh - Npx)` 不应机械替换；需要先确认页面父级是否能提供完整高度链，以及窄屏模式是否依赖自然内容高度。
- 当前证据主要来自 `usercenter-react` 的一次完整修复及后续演进。在另一个项目或独立场景复用并完成浏览器验证前，不提升为全局强制规则。
## Failed approaches
- 只在页面根节点增加 `flex-col` 或只在表格增加 `flex-1`：高度链仍可能在中间层中断。
- 只给最终内容区域增加 `overflow-auto`：默认 `min-height: auto` 仍可能让它撑高父级。
- 同时让 `<main>`、路由根节点和表格数据区滚动：容易出现双滚动条、滚轮焦点切换和分页被挤出视口。
- 通过 `calc(100vh - Npx)` 或 JavaScript 测量补偿标题高度：在标题、操作栏换行或应用外壳变化后容易产生新的固定偏差。
## Promotion record
- Not promoted. 当前已有一个项目中的修复、规范和后续演进证据，先保留为中央 candidate；待第二个项目或独立场景验证后，再考虑提升为 `patterns/` 下的前端布局模式或可执行浏览器检查。
AI Coding/inbox/index.md
+7
View File
@@ -0,0 +1,7 @@
# Inbox
保存刚从任务、用户纠正、失败路径或成功实践中提取的候选经验。
候选经验尚不能直接视为全局规则。验证后移动到 `learnings/`；没有复用价值的内容直接删除。
文件命名：`YYYYMMDD-short-slug.md`。