Sliye-AU

Imported from ELEVENBLACK41/Sliye-AU (AGENTS.md). Install upstream with npx skills add ELEVENBLACK41/Sliye-AU. Copyright stays with the author.

AGENTS.md

本文件是给 AI/Agent 的项目级协作说明。改代码前先读这里，再按需阅读 根 package.json、目标 app/package 的 package.json 和相关目录 README。

项目概览

• Monorepo：apps/web、apps/admin、apps/server、packages/ui、packages/contracts，admin端暂时停止开发
• 前端：Next.js App Router，业务模块放 src/features/<module>。
• 后端：NestJS + Prisma，业务模块放 apps/server/src/modules/<module>。
• 包管理：pnpm workspace，Node 版本以 .node-version / .nvmrc 为准。

项目说明

• 本项目是个个人项目，其目的主要是为了日后发展 拓展全栈技术，也是为了在简历上能留下一份好得个人项目，也是为了后续开源能为开源社区做出贡献，项目最终主要是想实现一个双端，web，app 端得一个决策记录系统，也可以不叫这个名字，我也没想好，主要是想实现一个决策记录得过程，后续主要是根据需求拉会，可以音视频开会，或者在群中讨论，讨论过程可以发议题或者是想法或者是决策最后投票之类的，一个决策得过程被记录了下来，后续还可以加入时间线回放，会议图谱之类得都可以。（待完善，会随着项目得进展不断新增功能或者删减/改变功能，如果你有更好得想法也可以跟我说），另外，admin端暂时不做了 将权限以及用户管理之类的模块打算放进web端 当成一个功能模块去做，admin端的开发暂时停止。

当前产品边界（重要）

• 当前项目只负责记录和呈现“一项决策如何产生”的全过程，核心链路止于形成正式决议并完成过程回放。
• 当前范围包括创建项目，项目下创建群，公共决策和小群决策的创建、参与人协作、会议/群聊讨论、提案、投票、正式决议、事件时间线和决策回放。

协作原则

• 先理解目录结构和现有写法，再动代码。
• 能用少得代码去写，就不要用多得代码去写
• 最小化改动代码 ，不要随意填冗余代码 过度设计防御性代码，即使填了后续不用也要删掉
• 页面都默认用中文。
• 暂时冻结 admin端，以模块形式先写进web端，以后没我得允许就不写admin了 只在web端写，后续根据权限去展示数据和模块以及功能
• 每次新增 package下的ui不要自己写 要安装shadcn ui
• 对于 包括但不限于 Select、Dialog、Popover、Tabs、Switch、Checkbox、Radio、Textarea 等等这类高强度复用的简单基础组件，一律优先使用 shadcn/Radix 组件，不要在业务页面里手写原生控件和样式；如果 packages/ui 里没有，先补 shadcn 组件再在业务中复用。
• 书写页面的时候要注意语义化。
• 不要为了维持现有技术栈而回避更合适的新技术。如果全局状态管理、Redis、消息队列、缓存、事件总线、分布式锁或其他库和技术栈，能够明显降低实现复杂度，解决跨页面、跨标签、跨进程或多实例的一致性问题，或者提升可靠性、性能和维护性，应主动评估并提出采用，不要勉强使用局部状态、内存单例或重复代码绕过。
• 引入技术应以真实问题和明确收益为依据，不为炫技堆叠依赖。新增框架、重型依赖或外部基础设施前，需要说明适用场景、预期收益、替代方案、接入成本以及部署和运维影响，并向我确认；范围内的轻量依赖可以作为正常实现步骤使用。
• 改动要小而清楚，不顺手做大重构。
• 不做顺便的事情，且我未明确要求的修改。
• 中文文档和注释使用 UTF-8；复杂逻辑写注释说明原因，每个函数前都要写注释，新建文件的时候也要在文件头写明这个文件是干什么的
• 不要写无关代码 以及很多强制防御性代码
• 不提交 .env、.next、dist、coverage、临时调试文件。
• 删除或移动代码前，先确认没有其他 app/package 依赖。

AI 计划小步执行规范（重要）

• AI 计划的实施应遵循项目路线图和对应的详细执行计划；本文件只规定协作规范，不记录阶段状态、完成情况、当前步骤或下一步。
• 阶段切换、完成标记和执行基线变更必须由老大确认，并同步更新对应计划文档；不得仅凭文件存在、单次测试通过或模型偶尔调用成功自动判定阶段完成。
• 默认每轮只完成一个边界明确、可以独立理解和验证的最小步骤，例如一组契约、一个评测样例、一项窄接口或一个单一职责组件；不得一次完成整个阶段，也不得跨阶段批量修改。只有老大明确要求扩大范围时才可以合并步骤。
• 每个步骤动手前，需要先向老大说明本轮目标、不做什么、预计涉及的主要文件和验证方式；如果发现实际影响明显超出本轮边界，应先停下并重新确认，不能顺势扩大改动。
• 每个步骤完成后，需要说明改了什么、为什么这样改、如何验证以及下一个建议的最小步骤，然后停止继续实现，等待老大检查代码或明确要求进入下一步。
• 小步执行以“单一职责、容易审查、容易回滚”为判断标准，不以凑文件数量或代码行数为目标；禁止借小步之名制造缺少必要验证、无法运行或无法理解的半成品。
• 不要求每个小步骤都执行全量 build。应根据改动风险选择最小且直接相关的验证：纯文档或低风险静态调整可以不运行构建；契约、状态机、权限、事务和跨端类型变化至少执行对应的定向测试或类型检查；只有跨 workspace 影响、发布前检查、框架配置变化或老大明确要求时才运行全量 build。
• 测试以风险和回归价值为准，优先覆盖权限、状态机、事务、并发、契约、数据边界和关键用户链路；避免重复覆盖、只验证实现细节或对实际行为没有保护价值的测试，不为凑覆盖率堆积用例。
• 稳定复用且能防止真实回归的单元、集成、端到端、契约测试和固定 Fixture 应保留；短时间 Smoke、临时调试路由、演示用 Mock、阶段验证脚本以及一次性测试数据，在验证完成并确认没有被代码、测试、脚本、文档或 CI 依赖后可以删除，不需要长期保留。
• 如果老大明确要求把某个步骤交给新的 Codex 任务执行，应优先指定 gpt-5.6-terra，并在任务说明中完整写明本轮边界、禁止事项、相关上下文和验收方式；新任务只执行被分配的这一个步骤，不得自动继续路线图中的后续工作。

AI 官方方案优先检查规范（重要）

• 遇到 AI SDK、流式响应、Tool Loop、Transport、Gateway、AI UI 组件、Markdown 流式渲染、长任务、重试、暂停/恢复或工作流问题时，必须先检查当前项目已安装版本对应的 Vercel 官方方案和仓库现有用法，再决定是否自定义实现。
• 优先检查顺序：Vercel AI SDK（Core/React/Transport/Tool Loop）→ Vercel AI Gateway（模型路由、回退、用量和观测）→ AI Elements 与 Streamdown（消息、会话、输入框和流式 Markdown 渲染）→ Vercel Workflow（持久化长任务、重试、暂停/恢复和调度）。
• 查找方案时先以本项目锁定的依赖版本、官方文档和官方源码为准；不得把其他版本的 API 形态直接套进当前代码。若官方能力无法满足需求，必须说明限制、替代方案和自定义实现的原因。
• 不要重复实现 Vercel 官方方案已经覆盖的协议、状态管理、流式解析、组件行为或工作流能力；新增重型依赖、Workflow、队列或基础设施仍需按真实收益、接入成本和部署影响向老大确认。

Bug 修复笔记规范

• 每次完成 Bug 修复后，都要同步新增或更新对应的修复笔记，笔记统一存放在 C:\Users\Sliye\iCloudDrive\iCloud~md~obsidian\mainSliye\个人Next+Nest决策音视频协作项目 下，并按实际业务模块归入相关的 Bug 修复笔记；不能只修改代码而不沉淀原因和处理过程。
• 同一个问题后续再次修复、补充边界场景或调整方案时，优先更新原笔记并追加变更记录，避免为同一问题创建多份相互冲突的笔记。
• 修复笔记至少要包含：问题现象、影响范围与复现条件、根因分析、修复方案与关键设计取舍、涉及的主要文件或数据变更、验证方式与验证结果，以及仍存在的风险或待观察项；没有的内容应明确写“无”，不要用猜测补全。
• 涉及数据库迁移、缓存、Redis、WebSocket、跨标签页同步、并发或多实例一致性时，需要额外记录数据兼容性、状态生命周期、失败恢复策略和部署顺序，便于后续排查线上问题。
• 笔记应在代码修复并完成必要验证后同步更新，内容必须与最终实现一致；如果由于目录权限、同步盘异常或其他原因无法写入指定目录，应在交付时明确说明，不能静默跳过。
• 笔记中不得记录密码、Token、Cookie、完整连接串或其他敏感信息；日志示例需要先脱敏。

分层习惯

• 页面和布局放在 src/app。
• 业务代码优先放在 src/features/<module>，内部可按 components、hooks、services、store、types 分层。
• 跨多个业务使用的组件放 app 内 src/components。
• 跨 web/admin 复用且无业务语义的基础组件，才沉淀到 packages/ui。
• packages/ui 只放基础 UI 和工具，优先复用 shadcn/Radix/lucide 风格；class 合并使用 cn。

API 与 contracts

• packages/contracts 是前后端共享类型契约包，包名 @workspace/contracts，在写这个的时候也要写注释。
• API 请求体、响应体、跨端共享枚举、认证用户、token 等结构放进 contracts。
• 页面表单、组件 props、后端实体、Prisma model、Nest 上下文、store 状态不要放进 contracts。
• contracts 只导出类型，不写请求函数、不放业务实现、不依赖 app 代码，共享类型也要写详细的备注
• 调用方使用 import type，例如：

import type { LoginRequestPayload } from '@workspace/contracts/auth';
import type { ApiResponse } from '@workspace/contracts/common';

• 后端 DTO 可以 implements 共享契约；DTO 仍负责 Nest/class-validator 等运行时校验。
• 前端服务层复用 contracts 的请求/响应类型，UI 表单类型保留在 feature 内。
• 每一个类型都要写注释，不然就忘了

请求链路

推荐链路：

Browser / SSR
  -> apps/web Route Handler 或 BFF
  -> apps/server NestJS API
  -> Prisma
  -> PostgreSQL

• 浏览器侧优先请求 Next.js 自身 /api/*，由 BFF 转发到 NestJS。
• 不在浏览器直接暴露后端内部地址，除非接口明确设计为公开接口。
• apps/web/src/services/request.ts 是前端请求入口；feature 内接口调用放 features/<module>/services。
• Nest service 返回真实业务数据，统一响应外壳由全局拦截器处理。
• 处理的异常等统一的最好能够写出枚举之类的 方便服复用，且理解代码。
• controller 保持薄，只做路由、参数接收和调用 service。
• 每一个接口也要写注释。

后端习惯

• 新模块放 apps/server/src/modules/<module>。
• controller 只处理 HTTP 层；service 负责业务逻辑、权限判断、事务和数据访问，业务逻辑也需要写注释。
• Prisma 查询优先集中在 service，不散落在 controller。
• 公共能力放 common，配置读取放 config 或通过 ConfigService 注入。
• Prisma migration 只通过 Prisma 命令生成，不手改历史 migration；不要手改 generated client。
• 权限判断放后端，前端只做展示和交互。

前端习惯

• App Router 默认 Server Component；只有需要交互状态、浏览器 API、事件监听、动画或客户端状态时才加 'use client'。
• 根据场景选择当前最优方式,例如客户端组件与服务端组件
• 页面中每一个函数前面应该都有备注
• 获取方式根据当前页面得数据量来放骨架，且如果是服务端组件得话骨架要能根据接口返回数据得时间相应，例如我得理解应该是SSR，服务端实时推送html字符串给前端渲染，根据场景选择
• 数据获取根据场景和复杂程度判断服务端获取还是客户端获取，交互型数据再放 client 侧。
• 优先 Tailwind CSS 4 和已有 CSS 变量。
• 按钮、Badge、基础控件优先复用 @workspace/ui。
• 新页面至少处理 loading、empty、error、success 四种状态。

组件拆分规范

• 组件按业务职责、状态归属和变更原因拆分，不为了减少行数机械拆文件，也不允许多个独立业务域长期堆在同一个 TSX 文件中。
• 页面或模块入口组件只负责数据接入、权限判断、布局和子组件组合；具体表单状态、事件处理和业务交互下沉到对应的 feature 业务组件。
• 单个 TSX 文件接近或超过 300 行时应主动评估拆分；超过 500 行原则上必须按职责拆分。配置密集但职责单一等特殊情况需要保留时，应写注释说明原因。
• 即使文件不足 300 行，只要同时包含多个可以独立迭代的业务区域、多个互不相关的状态集合或多组独立接口操作，也应提前拆分。
• 原则上一个文件只导出一个主要组件；仅供该组件使用、逻辑很小且不会独立迭代的私有辅助函数可以保留在同一文件。
• 状态放在最接近使用它的组件中；两个及以上业务组件复用的交互状态提取到 features/<module>/hooks，纯数据转换提取到 features/<module>/utils，共享常量放到语义清晰的 constants 文件。
• feature 内复用且带业务语义的组件保留在当前 feature；跨业务复用的 app 级组件放 src/components；跨 app 复用且无业务语义的基础组件才放 packages/ui。
• 拆分后使用具备业务语义的文件名和命名导出，避免 utils.ts、common.tsx、index.ts 这类含义模糊或形成大型聚合出口的文件。
• 不要把一小段只使用一次的静态 JSX、单个简单事件函数或强耦合的内部细节拆成独立文件，避免过度组件化增加跳转成本。
• 每个新建文件必须在文件头说明用途；组件、Hook、工具函数和共享类型继续遵守本项目的中文注释要求。

完成前检查

• 如果改动量很小，不用每次都跑检查，更不要求机械执行全量构建。
• 优先跑与改动范围直接相关的 lint/test/typecheck；只有确实需要验证产物、跨 workspace 集成或发布状态时才执行 build。
• 涉及环境变量时，同步更新 README 或项目说明，并提醒需要重启 dev server。
• 涉及 contracts 时，同步检查 server、web/admin 引用是否仍然通过类型检查。
• 代码格式就按照我文件.prettierrc的规则就行