Главная Обзор Помощь
Вход
ice-static
/
fmode-app
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: 37603a1e4e
Ветки Метки
fmode-app
/
CLAUDE.md

CLAUDE.md 15 KB
История Исходник

Claude Code 项目规则(FmodeStudio 规范包 · 阶段视图 2/4:设计建模)

本文件为 FmodeStudio 规范包的客户项目入口(自 stages/stage-2-设计建模-CLAUDE.md 派生并预填本项目信息)。 阶段视图机制:黄金规则 11 条 + AI 协作义务 + 环节-Skill 调用表全阶段常驻(本文件正文各阶段一致);仅「六、模块规则」@import 区块按阶段裁剪。阶段切换由 AI 自动执行——条件达成后 AI 直接编辑本文件「六、模块规则」区块为目标阶段清单并留痕,无需用户手动操作文件(清单与条件见包内《阶段视图切换指南.md》)。 规范母版(唯一权威源):随包 rules/(21 模块全集)、templates/(25 模板)、.claude/skills/(60 技能)、ui-kit/(官方组件底座)。客户项目内不修改 rules/ 内容;踩坑经验由交付方回写母版后随新版本同步。 规范版本:企业交付版 v1.0(自 FmodeStudio 平台版规范 v1.4 派生)| 更新日期:2026-08-19 | 同步至本项目日期:2026-10-14

当前阶段说明

  • 当前阶段:② 设计建模 + 设计系统(加载 6 个模块,等效约 330 行)
  • ⚠️ 本项目阶段② 含两个部分(用户裁决 6「先文档 → UI 设计 → 功能完善」):
    1. 设计建模(规范标准内容):数据范式文档(1NF/2NF/3NF 判定 + Schema + CLP)→ API 契约 → 建模评审
    2. 设计系统(本项目新增):设计令牌定稿 / 组件规范 / 关键页面原型 / 双端布局规范
  • 本阶段目标:产出可实施的完整设计规范,并通过评审闭环
  • 进入下一阶段的条件:数据范式文档 + API 契约评审通过(评审员子代理出具评审报告并修复闭环)
  • 切换动作(AI 自动执行,用户无需手动操作文件):条件达成后 AI 直接编辑本文件「六、模块规则」区块为目标阶段清单(清单见《阶段视图切换指南.md》),在 docs/00-tracking/操作追踪.md 留痕并简报
  • 需求回溯保障:需求变更时临时把 19 模块加回 @import(黄金规则 3 全程常驻兜底)
  • ⚠️ 本项目特有的硬门禁 G-D1:关键页面原型产出后必须先交用户查看确认(裁决 11),未确认不得进入编码

项目补充信息

  • 项目名称:fmode-app-v2 — Fmode 双端客户端(桌面横版 + 手机竖版)· 人机共生 IM 中枢
  • 应用类型与规模:单前端 Angular SPA(无自建后端);双端路由 /desktop/** + /mobile/**,约 20 条路由;不做响应式布局切换——入口页 replaceUrl 按 UA/视口一次性判定跳端,之后各端布局固定;两端共享 core/ 服务与 components/ 组件
  • fmode-ng 依赖版本与初始化 config 实例名:fmode-ng ^0.0.246,FmodeParse.with('nova') → appId ncloudmaster / serverURL https://server.fmode.cn/parse
  • 目录布局:单 Angular workspace(非 monorepo),根目录即应用;src/app/ 下计划 core/(共享服务)· components/(业务外壳组件)· ui/(ui-kit 官方底座,整目录接入,禁改)· desktop/ · mobile/ · pages/
  • config.json 位置与部署模式:不适用。纯前端 SPA,无 apps/server/config.json;数据访问与业务逻辑全部走 fmode 平台云函数(服务端托管),前端不持有任何服务端密钥
  • 前端技术栈:Angular 20.3.0 + 全 standalone 组件 + lazy loadComponent/loadChildren;Tailwind 3.4(preflight 正常启用) + ui-kit 官方组件底座(桌面 76 + 移动 71 组件),整目录接入 src/app/ui/;matrix-js-sdk ^42.4.0(懒加载 chunk,不进主包);@fortawesome/fontawesome-free ^7.3.1;Karma + Jasmine
  • 设计令牌真源:ui-kit 的 src/styles.uikit.css(:root / .dark / [data-accent] 语义 token:--canvas/--surface/--ink/--primary…)。禁止再造令牌前缀,禁止硬编码色值(存量项目 3 套前缀 + 321 处硬编码的教训)
  • 常用命令:
    • 本地开发:npm start(ng serve → http://localhost:4200/);强制某端可直开 /desktop/chat 或 /mobile/messages
    • 构建:npm run build
    • 测试:npm test(Karma + Jasmine)
    • 冒烟:NODE_PATH=$PWD/node_modules node scripts/smoke-imhub.js(待建,Playwright 双端全路由断言)
    • 部署:待定(见重建方案风险 R6)
  • 迭代记录见 docs/00-tracking/操作追踪.md;当前方案见 docs/02-design/plans/2026-10-14-v2重建方案.md
  • ⚠️ 待确认项(请勿擅自认定)
    • 黄金规则 2 提到的「PreToolUse hook 强制拦截 git 提交」:本项目 .claude/ 下当前只有 skills/,没有 settings.json,该 hook 未配置。在补齐前,「禁止自动提交」依赖本规则自律执行。
    • 后端云函数清单与契约(xlosi3m46q 状态、lfYlgU7SkK 交付物、RP5Ht55NeX provision、zl4yU8PAEB token-sync、AlP56LCKFm upload-url)散见于存量 README 与代码调用点,尚无集中的 API 契约文档,且字段定义未经核对(docs/02-design/database/ER-图-草案.md 中标 ❓ 者为逆向推测)。若触及后端契约,必须先补 docs/03-interface/api/。
    • tasks[] 多任务字段在存量系统中从未落库,"多任务并行"当前是宣传语而非实现(见访谈问卷 Q3.3-D1)。
    • 安全事项待处置:存量 E:\work\fmode-app\scripts\deploy.sh 有 4 个明文 OBS 凭证且已进 git 历史;存量 core/matrix-client.ts 有明文 TURN 凭据。均违反黄金规则 9,已列访谈问卷 S1/S2 待用户裁决。

一、身份与语言

  • 始终使用中文与用户交流、输出文档与提交信息。
  • 不编造、不臆测:信息不足时先提问,不猜测文件路径、配置、密钥、远程地址。
  • 一次只做一件事,不擅自扩大任务范围。

二、黄金规则(优先级从高到低,全阶段常驻)

  1. [必须] 先问后做,决策分层:需求不明确、存在多种方案、影响范围大、可能破坏既有功能时,必须先提问确认;按意图三分与澄清策略分级(高/中/低)决定问什么、问多少——业务语义/范围/验收口径等人级决策必须问用户,技术实现决策(schema 字段、表关系、接口形态)由 AI 定并留痕说明,禁止把技术细节抛给用户。
  2. [必须] 禁止自动提交:任何 git commit / git push 前必须征得用户明确同意(原由 PreToolUse hook 强制拦截;本项目暂未配置该 hook,见「待确认项」,更须自律)。
  3. [必须] PRD 阅读与执行:需求以 PM 产出的 PRD/MVP 范围/交接文档为准直接执行,禁止擅自增加页面/接口/需求;需求缺口与矛盾写变更请求回 PM 确认,禁止自行拍板。本项目需求源为 docs/01-requirements/prd/,存量基线正文见 E:\work\fmode-app\docs\。
  4. [必须] 文档同步:功能计划/逻辑变更必须先写或更新文档(技术方案/PlantUML 数据范式/API/修改留痕),再实现代码;实现完成后再次同步相关文档。
  5. [必须] 数据访问统一 fmode-ng 封装:前端与后端统一通过 fmode-ng(FmodeParse.initialize 仅初始化一次 + FmodeParse.with('nova') 取实例)访问数据,官方 parse SDK 仅经 fmode-ng 使用,禁止绕过封装裸调;禁止引入任何第三方 Parse 封装库。
  6. [必须] 平台铁律(红线):serverURL 只在初始化处配置一次,禁止散落各处;masterKey 与数据库密码不得出现在前端代码(仅 config.json 与服务端);删除用软删 isDeleted=true;业务表必须带 company: Pointer<Company> 多租户隔离;禁止让用户手动建表/连库/配服务器——由 FmodeSchema 与平台能力自动完成。
  7. [必须] 依赖按需引入:新增依赖必须说明理由并经用户确认;图标白名单按需引入,禁止全量引入。
  8. [必须] 测试通过才算完成:任何改动必须运行对应测试并输出验证证据,测试失败不得视为完成、不得提交;无法验证或降级处理的条目必须在交付时显式披露为「未验证项/已知限制」,禁止隐藏。
  9. [必须] 环境与密钥:config.json(含 masterKey/databaseURI)与 .env 不入 git;前端严禁出现 masterKey 与任何服务端密钥(含 OBS AK/SK、TURN 凭据);Nginx 配置入库;生产环境双重校验保证鉴权不可误关。
  10. [必须] 修改留痕与全程追踪:项目必须维护 docs/00-tracking/ 追踪体系——「操作追踪.md」按动作逐条追加(时间/内容/原因/涉及文件/关联设计文档链接),重大修改按日期新建当日文档;修改留痕带日期;任何操作可回溯「做了什么、为什么这么做」。
  11. [必须] 评审员隔离与子代理评审:复杂任务(≥3 文件/数据模型/安全权限)交付前派发独立评审员子代理(独立 prompt 只含技术栈事实+评审检查单+被评审物,不携带规范设计过程与本对话上下文),按指定技术栈专项评审;评审报告归档 docs/04-quality/review/,问题修复闭环(复审通过)后方可宣称完成。

三、AI 协作义务

  • 代码自查:AI 生成代码后必须自查——无调试残留 console.log、无死代码、无注释掉的旧逻辑、遵循最小改动。
  • 复杂任务先方案:≥3 文件/跨模块/数据模型变更/涉安全权限的任务,先输出方案(拆解、影响范围、验证路径)并通过规划门禁,确认后再动手。
  • 重大改动展示:涉及多文件、数据模型、接口签名变更时,向用户展示 diff 摘要后再继续。
  • 异常必须报告:发现文档与代码不一致、异常代码、缺失环境配置、可疑密钥或地址时,必须报告用户,禁止自行猜测或绕行。
  • 少打扰用户:技术决策 AI 自行决定并留痕;只在涉及业务语义时向用户确认;用业务语言解释做了什么,每完成一个可见里程碑就简报。
  • 会话收尾总结:重要开发会话结束时,输出三行总结(本次决策 / 踩坑 / 遗留事项与未验证项)。

四、规则分级与负面清单

  • 每条规则按 [必须]/[建议]/[禁止] 分级执行;冲突时高优先级规则优先。
  • 每个模块顶部设"负面清单(Do Not)",AI 动手前先自查负面清单。

五、常用命令

本项目为 npm + Angular CLI(非 pnpm monorepo),以 package.json scripts 为准:

  • 启动开发:npm start(ng serve → http://localhost:4200/);单端直开 /desktop/chat / /mobile/messages
  • 测试:npm test(ng test,Karma + Jasmine)
  • 构建:npm run build
  • 冒烟:待建(规划 npm run build && node scripts/smoke-imhub.js)
  • 部署:待定(重建方案风险 R6)

六、模块规则(@import 引入,阶段视图 2/4:6 个)

@rules/01-沟通协作.md:沟通协作规范 @rules/02-开发流程与文档同步.md:开发流程与文档同步(PRD 阅读与执行/四向追溯矩阵) @rules/03-项目架构与目录.md:项目架构与目录结构(fmode 平台目录) @rules/05-数据访问与数据库.md:数据访问与数据范式(fmode-ng/FmodeSchema/范式要求) @rules/18-UI设计规范.md:UI 设计规范(框架式:设计令牌/官方组件底座 ui-kit/防遮挡安全/可访问性) @rules/19-需求分析与挖掘.md:需求分析与挖掘(本阶段仅用 ER 图规范部分) @rules/21-评审与验收规范.md:评审与验收(强制评审节点/子代理评审员/评审报告闭环)

本项目调整说明:规范包的阶段② 标准清单为 6 个模块(01/02/03/05/19/21)。 本项目因用户明确要求"先出设计规范再写码"(裁决 6),额外加挂 @rules/18-UI设计规范.md,共 7 个。 该加挂属本项目特有需求,已在操作追踪中留痕(2026-10-14 阶段①→② 切换)。

七、技能库(.claude/skills/,随包复制到客户项目)

规则与技能的分工:规则保证下限(本文件与 rules/ 每次会话自动加载);技能提供上限(按需触发,重参考内容与完整方法论,避免规则膨胀)。

  • 本目录 .claude/skills/ 内置 60 个技能,连同 .claude/ 一起复制到客户项目即随行可用;
  • 技能触发方式:对话中直接说明或 AI 按需自动路由;需求挖掘环节的技能调用为强制(见 19 模块规则 6);
  • 模块中「重参考内容见技能 xxx」的条目,需要完整方法论时再加载对应技能。

八、环节-Skill 调用表(各环节需调用的技能,全阶段常驻)

环节 规范依据 必调/常用技能
1. 需求挖掘 19 模块 brainstorming、grill-me、grilling、to-questionnaire、ralph、research、to-spec、to-tickets
2. 建模与架构 19 规则 5;05 范式 domain-modeling、codebase-design、prototype、writing-plans、planning-with-files
3. 编码实现 06/07/13/16 code、coding-guide、karpathy-guidelines、implement、dev-expert
4. 测试验证 08 tdd、test-driven-development、verification-before-completion
5. 代码评审 21 code-review、requesting-code-review、receiving-code-review、subagent-driven-development
6. 调试诊断 08;15 systematic-debugging、diagnosing-bugs、wait-what
7. 执行交付 17;02 executing-plans、dispatching-parallel-agents、finishing-a-development-branch、using-git-worktrees、handoff、claude-handoff
8. UI 设计 18 ui-new、ui-ux-pro-max、superdesign、ui-ux-design、ui-audit
9. 工程基线 13;12 setup-ts-deep-modules、migrate-to-shoehorn、improve-codebase-architecture、scaffold-exercises、setup-pre-commit
治理(横切所有环节) 09;10 git-guardrails-claude-code、resolving-merge-conflicts、using-superpowers、writing-for-agents、writing-skills、teach

九、本项目特有的适配说明(自规范包引入时新增,供后续维护者参考)

  • ui-kit 使用方式(与旧项目相反):包内 ui-kit/ 正式要求 Angular 20.3.x + Tailwind 3.4.x + FontAwesome ^7.3.1。本项目 Angular 20.3.0,因此 ui-kit 整目录接入、原生使用,不再只是"参考实现"。接入方式:ui-kit/src/app/ui/** → src/app/ui/(596 文件,组件间有交叉引用,必须整目录复制);styles.css → src/styles.uikit.css;src/app/ui/** 属底座,禁止修改。
  • 样式加载顺序(见 angular.json 与 src/styles.scss)必须保持:styles.uikit.css(语义 token + Tailwind 三指令)→ FontAwesome → styles.uikit.scss(动画工具类)→ styles.scss(应用层兜底)。
  • 业务样式一律进组件;src/styles.scss 只放 html/body 基础与 iOS 输入字号修复等无法进组件的项。
  • 规范包文件清单(2026-10-14 引入):
    • CLAUDE.md(本文件,自 stages/stage-1-需求挖掘-CLAUDE.md 派生并预填)
    • rules/(21 模块全集) · templates/(25 模板) · .claude/skills/(60 技能) · stages/(4 阶段入口)
    • ui-kit/(官方组件底座)
    • 阶段视图切换指南.md · 阶段意图与技能规则速查.md · 规范包-CHANGELOG.md
  • 与源项目无关:规范包来源仓库为另一个项目(通用 AI 陪练基座),其 apps/、packages/ 等业务内容未引入;本项目 docs/ 为 fmode-app-v2 自有内容。
  • 与存量项目的关系:E:\work\fmode-app(Angular 19)保留原地作为迁移参考,只读不修改。禁止把存量代码直接拷贝进 v2——所有实现必须按 v2 规范重写。
  • 阶段② 为本项目新增环节:用户明确要求"先出设计规范再写码"。阶段② 产出设计令牌定稿 / 组件规范 / 关键页面原型 / 双端布局规范,并设门禁:设计规范未定稿不得进入编码。