文章目录概要npm 相关命令docker相关命令git 相关命令powershell相关命令数据库相关问题概念问题RBAC基于角色的访问控制—— 推荐方案TDD测试驱动开发概要npm 相关命令功能测试npm--prefix backend test--tests/api/activities.location-filter.test.ts部分具体含义npmNode.js 包管理工具用于执行项目脚本这里是运行测试--prefix backend指定命令的执行目录为backend后端项目根目录避免需要手动cd backend再执行命令test执行backend目录下package.json中定义的test脚本通常是 Jest/Mocha 等测试框架的启动命令--分隔符前面是 npm 命令参数后面是传递给测试脚本的参数tests/api/activities.location-filter.test.ts指定只运行这一个测试文件而非全部测试精准测试地点筛选功能执行定义的脚本npm--prefix frontend run lint命令部分具体含义npmNode.js 包管理工具执行前端项目的脚本命令--prefix frontend指定命令执行目录为frontend前端项目根目录无需手动cd frontendrun lint执行frontend/package.json中定义的lint脚本该脚本已配置 ESLint/Prettier 等工具的校验规则docker相关命令容器内操作dockerexecsupabase-db psql-U postgres-d postgres-c\d public.profiles命令部分具体含义docker exec supabase-db在运行中的supabase-db容器Supabase 的 PostgreSQL 数据库容器内执行命令psql -U postgres用 PostgreSQL 超级用户postgres连接数据库-d postgres连接到默认的postgres数据库-c \d public.xxx执行 PostgreSQL 内置命令\d查询指定表的详细结构\d public.profiles重点\d是 PostgreSQL 的元命令非 SQL作用是查看表的完整结构- 字段名、数据类型、约束主键 / 外键 / 非空- 索引、默认值、注释- 比单纯的\d显示更多细节比如存储参数、统计信息dockerexecsupabase-db psql-U postgres-d postgres-cselect id, title, location from public.activities order by created_at desc;命令部分具体含义docker exec supabase-db在运行中的supabase-db容器Supabase 的 PostgreSQL 数据库容器内执行命令psql -U postgres用 PostgreSQL 超级用户postgres连接数据库-d postgres连接到默认的postgres数据库-c select ...执行引号内的 SQL 查询语句执行后退出select id, title, location from public.activities查询activities表的 3 个核心字段-id活动唯一 ID定位具体数据行-title活动标题快速识别是否为测试数据比如标题含「测试」「test」-location活动地点辅助识别测试数据比如地点为「测试地址」order by created_at desc按created_at创建时间降序排列最新创建的测试数据会排在最前面更容易识别dockerexecsupabase-db psql-U postgres-d postgres-cselect conname, conrelid::regclass as table_name from pg_constraint where confrelid public.activities::regclass and contypef;命令部分具体含义docker exec supabase-db psql -U postgres -d postgres -c基础逻辑和之前一致进入 Supabase 数据库容器用postgres用户连接数据库执行后续 SQLselect conname, conrelid::regclass as table_name查询两个核心字段-conname外键约束的名称比如activity_members_activity_id_fkey-conrelid::regclass as table_name将系统内部的表 IDconrelid转换为可读的表名比如public.activity_membersfrom pg_constraint从 PostgreSQL 系统表pg_constraint查询该表存储所有数据库约束主键、外键、唯一键等where confrelid public.activities::regclass筛选条件 1只查「引用的主表」是public.activities的约束confrelid 外键指向的主表 IDand contypef筛选条件 2只查外键约束contypef中f foreign key主键是p、唯一键是u列出正在运行的容器docker ps--formattable {{.Names}}\t{{.Image}}\t{{.Ports}}命令部分具体含义docker psDocker 核心命令列出正在运行的容器如果加-a会列出所有容器包括停止的--format自定义输出格式让结果更规整、只显示需要的信息避免默认输出冗余内容table {{.Names}}\t{{.Image}}\t{{.Ports}}定义输出为 “表格格式”只显示 3 个核心字段-{{.Names}}容器名称比如supabase-db、supabase-api-{{.Image}}容器使用的镜像比如supabase/postgres-{{.Ports}}容器映射的端口比如5432/tcpPostgreSQL 默认端口-\t制表符分隔字段让表格对齐git 相关命令避免把产物文件提交Add-Content.gitignorenbackend/node_modules/nbackend/dist/n*.dev.out.logn*.dev.err.loggit status--short命令部分核心解释为什么这么做Add-Content .gitignore [内容]Windows PowerShell 命令向.gitignore文件末尾追加新的忽略规则-n换行符避免规则挤在一起-backend/node_modules/忽略后端依赖包目录体积大、无需版本控制-backend/dist/忽略后端构建产物可通过源码重新构建-*.dev.out.log/*.dev.err.log忽略日志文件临时产物。⚠️ 如果是 Linux/Mac 终端改用echo -e ... .gitignore。核心目的避免把无意义的产物 / 日志文件提交到 Git 仓库减少仓库体积也避免多人协作时因这些文件产生冲突。git status --short再次检查状态确认被忽略的文件是否从 “未跟踪??” 状态消失。验证忽略规则是否生效防止漏加规则导致不该提交的文件被暂存。暂存并人工确认提交内容git add-A git diff--staged--name-only命令部分核心解释为什么这么做git add -A-A--all暂存所有修改包括已跟踪文件的修改、删除以及新增的未跟踪文件但.gitignore 里的文件除外。把所有需要提交的代码变更纳入 “暂存区”为后续提交做准备。git diff --staged --name-only--staged查看暂存区的变更--name-only只显示变更的文件名不显示具体代码差异。人工核对确认暂存区里只有需要提交的业务代码没有误加的产物 / 日志文件这是 “防错关键步骤”。如果暂存里还有不该提交的文件取消暂存git restore--staged backend/node_modules backend/dist backend.dev.err.log backend.dev.out.log frontend.dev.err.log frontend.dev.out.log git diff--staged--name-only命令部分核心解释为什么这么做git restore --staged [文件/目录]把指定文件 / 目录从 “暂存区” 移除但保留本地文件不变相当于 “取消暂存”。⚠️ 旧版 Git 可用git reset HEAD [文件]效果相同。兜底措施如果步骤 3 发现暂存区有不该提交的文件比如漏加.gitignore 导致 node_modules 被暂存用这个命令撤销暂存避免误提交。git diff --staged --name-only再次查看暂存区确认误暂存的文件已被移除。验证取消暂存操作生效确保最终提交内容纯净。合并到 main走 PRgh pr create--base main--head feature/socialvibe-stability-chat--titlefeat: stabilize chat flow--body...命令部分核心解释为什么推荐gh pr create [参数]ghGitHub CLI 工具需提前安装配置--base mainPR 的目标分支是 main--head [功能分支]PR 的源分支是功能分支--titlePR 标题--bodyPR 描述比如修改内容、测试情况、关联的需求 ID 等。团队协作的最佳实践1. PR 支持代码审查Code Review让同事检查代码问题2. 可配置 CI/CD 自动跑测试、构建确保合并后 main 分支稳定3. 留下合并记录便于追溯和管理。合并完成后清理 worktreegit worktree remove D:\codex_code\socialvibe\.worktrees\socialvibe-stability-chat git branch-d feature/socialvibe-stability-chat命令部分核心解释为什么这么做git worktree remove [worktree路径]删除该功能分支对应的独立工作树目录。清理磁盘空间避免多个无用的 worktree 目录堆积。git branch -d [分支名]-d删除本地功能分支仅当分支已合并到 main 时才能删除如果要强制删除未合并的分支用-D。保持本地分支列表整洁避免分支过多导致管理混乱。从跟踪中移除git rm-r--cached backend/node_modules backend/dist.npm-cache部分含义-r递归处理目录因为后面跟的都是文件夹backend/node_modules后端目录下的 Node.js 依赖包体积大、无需版本控制backend/dist后端代码构建后的产物编译后的文件可通过源码重新生成.npm-cachenpm 的缓存目录临时文件无需追踪git rm --cached命令的核心作用是将指定文件 / 目录从 Git 的追踪列表中移除但保留本地文件git rm本意是删除文件并从 Git 追踪中移除--cached关键参数只移除 Git 追踪关系本地文件完全保留如果不加这个参数本地文件也会被删除-r递归处理目录针对文件夹比如node_modules这种包含大量子文件的目录必须加。powershell相关命令执行SQL将核心数据写如本地supabase数据库$ Get-Content-Raw admin-system/database/supabase/seeds/seed_core.sql|dockerexec-i supabase_db_supabase-project psql-U postgres-d postgres命令 / 参数作用$终端提示符仅视觉标识非命令部分Get-Content -Raw admin-system/database/supabase/seeds/seed_core.sqlPowerShell 读取文件-Get-Content读取文件内容--Raw以 “原始字符串” 方式读取保留 SQL 脚本的换行、格式避免分段执行导致语法错误- 路径指定种子文件的位置|管道符将前一步读取的 SQL 内容作为输入传递给后一步命令docker exec -i supabase_db_supabase-projectDocker 执行命令-docker exec在运行中的 Docker 容器内执行命令--i交互式模式保留标准输入允许通过管道传递 SQL 内容-supabase_db_supabase-projectSupabase 数据库容器的名称本地运行的 PostgreSQL 容器psql -U postgres -d postgresPostgreSQL 客户端命令-psqlPostgreSQL 的命令行客户端--U postgres指定连接数据库的用户Supabase 默认管理员用户是 postgres--d postgres指定连接的数据库名称Supabase 默认数据库是 postgres删除文件$ Remove-Item-Recurse-Force supabase-project/supabase命令部分具体作用说明Remove-ItemPowerShell 中用于删除文件 / 文件夹的核心命令等同于 Windows CMD 的del/rd或 Linux/macOS 的rm-Recurse必选参数删除文件夹时表示递归删除不仅删除文件夹本身还会删除其中所有子文件、子文件夹因为supabase文件夹包含运行时生成的多层目录和文件-Force强制删除参数- 跳过删除前的确认提示无需手动确认- 可以删除隐藏文件 / 系统文件Supabase 运行时可能生成隐藏配置文件- 忽略文件 / 文件夹的只读属性supabase-project/supabase要删除的文件夹路径-supabase-project是项目根目录或父目录-supabase是 Supabase 运行时自动生成的文件夹包含本地数据库数据、配置缓存、日志等临时 / 运行时文件。执行全局脚本powershell-ExecutionPolicy Bypass-File admin-system/scripts/verify.ps1命令片段中文释义核心作用补充说明powershell调用 PowerShell 解释器启动 PowerShell 程序作为执行脚本的运行环境系统级命令需确保 PowerShell 已安装Windows 自带macOS/Linux 需手动安装-ExecutionPolicy Bypass执行策略设为 “绕过”临时跳过 Windows 默认的 PowerShell 脚本执行限制1. Windows 默认执行策略如Restricted会禁止运行本地未签名脚本2. 该参数仅对本次执行生效不会修改系统永久策略3. 核心目的让verify.ps1能正常运行无需手动修改系统权限-File指定要运行的脚本文件告诉 PowerShell后续路径是要执行的.ps1脚本文件必选参数若省略会把脚本路径当作普通字符串处理无法运行脚本admin-system/scripts/verify.ps1验证脚本的路径指向项目中用于全流程验证的 PowerShell 脚本该脚本通常包含✅ 代码语法检查✅ 项目构建编译 / 打包✅ 单元测试 / 集成测试✅ 依赖完整性校验✅ 输出最终验证结果成功 / 失败文件移动$ Move-Item-Path D:/codex_code/ai_workbench/frontend/package-lock.json-Destination D:/codex_code/ai_workbench/frontend/package-lock.pre-real-impl-backup.json命令 / 参数作用$终端提示符仅视觉标识非命令的一部分Move-ItemPowerShell 核心命令移动 / 重命名文件相当于 Linux 的mv命令-Path D:/codex_code/ai_workbench/frontend/package-lock.json源文件路径指定要备份的本地package-lock.json位置-Destination D:/codex_code/ai_workbench/frontend/package-lock.pre-real-impl-backup.json目标文件路径- 将源文件重命名为package-lock.pre-real-impl-backup.json保留在同一目录- 命名规则pre-real-impl-backup清晰标识这是 “应用真实实现前的备份文件”便于后续识别数据库相关问题以supabase为例SERVICE_ROLE_KEY和ANON_KEY区别是什么为什么在部署的时候后端需要填写前者前端需要填写后者这两个密钥都是 Supabase 提供的API 访问凭证核心差异是权限等级和使用场景理解这一点就能明白 “后端用 SERVICE_ROLE_KEY前端用 ANON_KEY” 的根本原因 —— 本质是为了权限最小化和安全防护。密钥类型权限等级本质适用场景ANON_KEY匿名密钥极低权限仅能访问你在 Supabase 中显式允许匿名用户访问的数据 / 功能面向前端的 “受限凭证”前端浏览器 / 移动端直接调用 Supabase APISERVICE_ROLE_KEY服务角色密钥最高权限绕过所有 Row Level Security (RLS) 规则可操作 Supabase 中所有数据 / 功能增删改查、管理用户、执行存储过程等面向后端的 “超级凭证”后端服务器Node.js/Java 等调用 Supabase API概念问题RBAC基于角色的访问控制—— 推荐方案1核心定义RBACRole-Based Access Control是行业主流、实现成本低、易维护的权限模型核心逻辑是先定义「角色」如 super_admin/admin/analyst/viewer给「角色」绑定「权限」菜单可见性、接口访问权限、操作按钮权限给「用户」分配「角色」一个用户可绑定多个角色最终用户的权限 所有绑定角色的权限合集。你提到的四级角色权限边界角色核心权限权限边界菜单 / 接口粒度super_admin全量权限所有菜单可见 所有接口可访问含权限配置、用户管理、系统配置、数据操作、日志查看等admin业务管理权限无系统配置 / 权限管理业务菜单项目管理、沙箱运行、日志查看 业务接口导入 / 启动 / 停止项目无用户 / 角色管理权限analyst只读 数据分析权限无操作权限所有菜单可见仅展示 只读接口查看项目 / 日志 / 状态无导入 / 启动 / 停止 / 删除等操作权限viewer基础只读权限无数据分析仅核心菜单项目列表、基础日志 基础只读接口无数据分析、系统配置相关权限优势实现简单主流框架如 Spring Security、Casbin都有成熟的 RBAC 插件无需从零开发易理解 / 易维护角色层级清晰管理员可通过后台直接配置「角色 - 权限」映射无需改代码适配中小规模系统你的 Vite 工作台属于中小规模工具类系统四级角色完全覆盖需求审计便捷可通过「角色」快速追溯用户权限范围符合合规要求。劣势灵活性有限权限仅绑定角色无法根据「数据范围」「时间」「环境」等动态条件控权如 “仅允许 admin 查看自己创建的项目”角色膨胀风险若后续需细分权限如 “仅允许导入 ZIP 不允许导入文件夹”可能需要新增角色如operator_zip。TDD测试驱动开发你先按照 TDD 规范为后端核心功能数据库 schema、工具函数、路由接口编写了一批「故意让其失败」的单元 / 路由测试用例这些测试现在会失败因为对应的功能代码还未实现后续你会根据测试的失败结果逐步补全实现代码最终让测试通过红→绿→重构。简单说你先定义了 “功能要满足什么条件”测试用例再去写代码实现功能而非先写代码再补测试 —— 这是 TDD 的核心思想能保证代码从一开始就符合预期行为。所有测试文件都基于Vitest前端 / Node.js 主流测试框架编写遵循describe测试套件it测试用例expect断言的标准结构:schema.test.ts— 数据库表结构生成测试import{describe,expect,it}fromvitest;import{createSchemaSql}from../../../../server/db/schema;describe(schema,(){it(contains projects table creation,(){const sqlcreateSchemaSql();expect(sql).toContain(CREATE TABLE IF NOT EXISTS projects);});});测试目标验证createSchemaSql()函数生成的 SQL 语句中包含「创建 projects 表」的语句✅ 现在运行测试会失败因为createSchemaSql()还没实现或返回的 SQL 不含该语句❗ 后续你需要实现createSchemaSql()让它生成包含CREATE TABLE IF NOT EXISTS projects的 SQL直到测试通过核心价值确保数据库 schema 生成逻辑不会遗漏 projects 表避免后续数据库无该表导致功能报错。viteInspector.test.ts— Vite 项目检测工具函数测试import{describe,expect,it}fromvitest;import{detectPackageManager,inspectViteProjectFiles}from../../../../server/lib/viteInspector;describe(viteInspector,(){it(prefers pnpm lockfile,(){expect(detectPackageManager([pnpm-lock.yaml])).toBe(pnpm);});it(marks missing package.json as invalid,(){const reportinspectViteProjectFiles([index.html,src/main.tsx]);expect(report.valid).toBe(false);});});测试目标验证两个工具函数的核心逻辑①detectPackageManager检测到pnpm-lock.yaml文件时返回包管理器为pnpm②inspectViteProjectFiles项目文件中缺少package.json时标记项目为无效valid: false持续更新