CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

这是一个中文商业策划文档仓库(为科技园区旁的「特色烧烤 × 轻社交目的地」筹划开业),不是软件工程项目:没有 package.json、没有构建/测试/lint 命令。这里的「源码」是 Markdown,「构建产物」是 PDF / HTML / PNG / M4A。所有沟通与产出默认用中文。

仓库性质与最高纪律:单一真相源(SSOT)

• 当前真相的唯一入口 = 商业策划3.0·当前版.md。它合并了 1.0 + 2.0 + 互动玩法 + 自动化 + 开业筹备 P0–P8。任何冲突一律以 3.0 为准。
• 旧版本只降级、不删除:1.0(烧烤场商业策划全案.md)和 2.0(烧烤场商业策划2.0.md)已降为历史底稿,归档在 历史底稿/。改动现状时改 3.0,不要改历史底稿;历史底稿是不可变的版本快照。
• 3.0 是索引 + 当前口径,细节仍分散在各源文档(每节给相对链接)。修改某个细节时,优先改对应源文档,再回 3.0 校准索引/口径;不要让 3.0 与源文档产生新的冲突。

新想法的落点(别污染 SSOT)

• 新点子先进 想法收集箱.md(零门槛 inbox,非 SSOT),不要直接写进 3.0——3.0 只放已定口径。
• 成型后按收集箱里的分诊去向表毕业到对应 live 文件:玩法→互动活动与玩法2.0.md、菜品/酒水→开业筹备/P3、营销→开业筹备/P6、命名/VI→开业筹备/P3;需要老板拍板的取舍直接进 3.0 §11 待拍板清单,拍板后移到「🔒 已拍板决策」。
• 用户随口说的新想法,默认帮他记进收集箱「## 待分诊」,而不是当场塞进正式文档。

目录角色(读多个文件才能看清的大图)

_parts3/ 数据流水线(Todolist HTML 的来源)

生成顺序与职责(历史底稿/_parts、_parts2 是旧版同构产物):

1. research.json — 异构联网调研,对照行业 checklist 校验 9 阶段 × 8 工作流是否 MECE(不漏桶)。
2. audit.json — MECE 审计结论:verdict + gaps(缺口)+ 职责交叠 + 依赖问题。
3. phases.json — 规范化的 9 阶段 → 工作包 → 149 任务树,每个任务带 owner / weeks / deps / acceptance / gate / workstreams / template。
4. checklist_data.json — 烘焙进 HTML 的最终数据。

烧烤场开业Todolist.html 把数据内联(inline)进去了,不是运行时 fetch(全文件只用 localStorage 存进度)。因此改任务数据要回到 _parts3/checklist_data.json 重新生成 HTML,不要直接手改 149KB 的 HTML 正文。

内容里的「承重」不变量(改动必须保留)

这些不是普通文字,是被下游(HTML 锁逻辑、审计、财务模型)依赖的约束:

• 三条生死红线:① 用地性质能否作餐饮 ② 夜间噪音 ≤50dB ③ 明火 + 篷布 + 燃气的消防耦合。
• Gate-0 门禁(内容 + HTML 双重生效):P1 的 7 项合规核验(用地 / 消防 / 环保)全部勾选前,P4 的土建/采购任务在 HTML 里自动锁定(灰色)。phases.json 里 P1/P2 的 gate:true 与 P4 任务对 Gate-0 的 deps 必须保持一致——动了门禁结构要同步三处:内容、phases.json deps、HTML 锁逻辑。
• MECE 结构:一级=9 个时间阶段(P0→P8,互斥穷尽);二级=工作包;三级=149 任务;横切=8 个工作流标签(法务合规 / 财务资金 / 品牌营销 / 产品出品 / 工程施工 / 设备系统 / 人力组织 / 运营安全)。新增任务必须归入某个既有阶段 + 1–2 个既有标签,不要新增一级阶段或第 9 个标签(audit.json 已论证二维切法 MECE 成立)。
• 财务锚点(改一处需全仓一致):固定成本 ≈33.5 万/月、盈亏平衡 ≈81 万、转正门槛 84–88 万、总投资 315–380 万。
• 定位口径:唯一护城河 = 「篷开露星空」;明火炭烤 = 产品力底座;自动化传菜 = 出片彩蛋(不对外讲「科技感差异化」)。

编辑约定

• 模板里的斜体 *(填写建议:…)* 是占位提示,不是垃圾——填写时替换成真实内容,不要当无关文字删掉。
• 模板里的数字带行业区间,并标注 法定 vs 经验(如食材率 32–38%、油烟 ≤1.0mg/m³、储值不记名卡 ≤1000 元、抽奖奖额 ≤5 万)。改数字时保留这个「法定/经验」标注。
• 相对路径不能破:烧烤场开业Todolist.html 与 开业筹备/ 模板靠相对链接互通(任务的 📄 徽章直达模板),部署时两者要一起、保持相对结构。
• 文件名含中文、含 · 与全角括号是有意为之;脚本/命令里引用这些路径要正确转义。
• .claude/ 等未被忽略;不要 git add -A / git add .,只 stage 明确路径。

「构建」= 用 skill 重新生成派生产物(无 npm script)

本仓库没有传统构建系统。派生产物由用户的 Claude skills 生成:

• .md → 交互式单文件 HTML:report-to-html skill。
• .md → 好听的叙述音频 .m4a:report-to-audio skill。
• research.json 那类异构联网调研:survey / deep-research skill。
• PDF / PNG 为打印/导出产物。

改了源 .md 或 _parts3/*.json 后,对应派生产物会过期——按需用上述 skill 重新生成,而不是手改产物文件。Todolist 用法/部署细节见 开业筹备/_使用说明.md。

文档门户 门户/(Astro,有 npm script;唯一例外)

门户/ 是一个 Astro 静态站,把仓库根的全部 .md 渲染成可浏览 + 中文全文搜索(Pagefind)+ 导 PDF 的门户,并内置开业任务追踪页(Gate-0 锁)。它是派生产物,源仍是那些 .md(SSOT);门户只读、绝不写回 md。

• 重建:cd 门户 && pnpm install && pnpm build(产物在 门户/dist/;pnpm preview 本地看;pnpm dev 热更新但搜索仅构建后生效)。改了任何 .md 后重跑 pnpm build 即同步。
• 就地读取:门户/src/content.config.ts 的 glob loader base:'../' 就地读 仓库根的 md,一个文件都不搬。新增 md 自动收录到全景图(门户/src/lib/nav.ts 注解过的归对应层,没注解的进「未归类」)。
• 任务契约(承重):门户任务页直读 门户/src/data/contract.json,由 门户/scripts/build-contract.mjs 从 _parts3/checklist_data.json(149 任务=唯一真相,非 phases.json 的 137) 生成并构建期断言 149/gateTasks7(含 P1.A.1)/gateBlock19,违反即 build 红。改任务数据仍回 _parts3/checklist_data.json,不要手改 contract.json 或 HTML。
• 固化校验(门户/scripts/check-all.mjs,构建期阻塞):① 跨 md 断链(基线 links-baseline.json,新增断链阻塞,修好后 pnpm check:baseline 收紧)② 财务锚点跨 SSOT 一致(门户/anchors.json,改一处忘改另一处即红)③ 派生过期(WARN)。动了财务锚点/移动 md/改链接后,以 build 是否绿为准。
• 团队共享(M3 轻后端):server/serve.mjs 是零依赖薄后端(只用 Node 24 内置 node:sqlite/node:http),pnpm serve 启动,serve 构建好的 dist + /api/*(团队共享勾选 + ROI 场景持久化)。前端自动判模式:有后端=团队共享(每 8s 轮询),无后端=本地 localStorage。登录=团队共享密码(TEAM_PASSWORD 环境变量,默认 shaokao2026 会告警),写需登录、读公开。数据在 server/data.db(gitignore)。部署=局域网 IP,免备案。模板表单化:schema 驱动(src/data/forms.json 加一段=一个新表单,通用渲染器 pages/form/[...t].astro 自动出页接 /api/forms),已做 P0 三个(可行性/客群验证/立项决议),余 32 个按需加 schema。
• 门户/ 已被 门户/.gitignore 忽略 node_modules/ dist/ .astro/ server/*.db;别 git add -A。旧 烧烤场开业Todolist.html 暂留(未删),门户达完全平替再退役。