xfcycc Obsidian Project Logic Docs
用于把代码中真实存在的字段取值方式、计算逻辑、业务规则、接口逻辑，整理进本地 Obsidian 项目资料。默认中文。
硬约束
- 先找项目、笔记名、章节；找不到就继续查，不要把内容写进相似但不确定的文件。
- 写入 Obsidian 前必须二次确认，即使用户说“更新到 Obsidian”也先预览。
- 不凭记忆写口径；必须回到代码、接口、配置、SQL、日志、提交 diff 或现有正式文档核对。
- 只改用户要求的目标笔记和目标章节，不顺手整理其他笔记。
- Obsidian 正文保持干净，不写内部推理、工具输出、memory citation、“我检查了...”这类过程说明。
- 用户只要总结时，只输出总结；用户要求写入时，先给确认预览，收到明确确认后再落盘。
工作流
1. 定位项目和笔记
先确认当前工作区和真实子仓：
pwd
find . -maxdepth 2 -name .git -type d -prune
再定位 Obsidian 项目资料。优先顺序：
- 用户点名的项目、笔记名、章节。
- 当前工作区或 memory 中已知的项目资料目录。
- 本地 vault 常见目录：
/Users/caiguoyu/Library/Mobile Documents/iCloud~md~obsidian/Documents/cainiao/项目资料
常用查找：
rg -n "<项目名>|<模块名>|<笔记名>|<章节关键词>" "<项目资料目录>"
find "<项目资料目录>" -maxdepth 8 -type f -name "*<关键词>*.md"
确认目标时至少锁定：
- 项目目录，例如
项目资料/盛迭/节能管理。 - 目标笔记绝对路径，例如
.../节能管理-个人功能开发说明.md。 - 目标章节标题，例如
## 1.大家乐大屏字段或### 当前实现口径。
2. 回到事实源核对
按任务类型读事实源：
- 字段取值方式：读前端展示字段、接口模型、VO/DTO、Mapper SQL、service 组装逻辑。
- 计算逻辑：读计算入口、私有计算方法、SQL 聚合、常量、阈值、空值/负数/无数据处理。
- 业务逻辑：读 controller/service/manager 流程、状态枚举、表字段、现有项目说明。
- 接口逻辑：读 controller 路径、前端 API 调用、请求/响应模型、拆分接口、刷新方式。
- 运行态问题：读配置、日志、实际请求结果；不要只看源码推断。
记录口径时要保留这些要素：
- 数据来源：表、字段、接口、配置项、常量。
- 时间范围：今日、昨日同一时段、本月、最近 N 天、当前时刻。
- 计算公式：用可读公式写清楚分子、分母、边界。
- 过滤条件：删除标记、状态、有效门店、有效基线、设备类型、阈值。
- 边界处理：空值、0、负数、无数据、样本不足、兜底值。
- 前后端关系：接口是否拆分，前端是否二次过滤、格式化、合并多个接口。
3. 对齐目标笔记格式
先读目标文件上下文，不要新造风格：
sed -n '1,180p' "<目标笔记>"
如果目标已有字段表，优先沿用它的列。常见列：
模块 | 字段名 | 类型 | 关联表/字段 | 说明 | 示例 | 单位 | 备注
如果需要补充长口径，优先新增或更新一个小节，常用结构：
### 当前实现口径
接口入口：
- ...
时间口径：
- ...
字段取值与计算：
- ...
状态、告警与边界：
- ...
写法要求：
- 用业务可读语言，不只贴类名或方法名。
- 公式写全，例如
今日节能量 = max(日基线 - 今日实际用电, 0)。 - 表格中旧口径要直接替换，不在旁边追加矛盾说明。
- 对“暂定”“待定”“旧接口”等过时描述，要改成当前已核实口径。
4. 写入前二次确认
在动文件前，先发给用户确认预览。必须包含：
- 目标文件绝对路径。
- 目标章节或插入位置。
- 本次会新增/替换的内容摘要。
- 一段可读预览，足够判断格式和内容。
- 事实源摘要，例如“已对照 service、Mapper XML、前端 API 调用”。
确认话术保持简短：
我准备写入：
目标文件：...
目标章节：...
改动摘要：...
预览：
...
你确认后我再写入。
只有用户明确回复“确认”“可以”“写入”“更新吧”“ok”等，才编辑文件。
5. 写入和验证
确认后使用 apply_patch 做最小修改。不要用 shell 重写整篇笔记。
写完后回读目标区域：
sed -n '<start>,<end>p' "<目标笔记>"
rg -n "<关键公式>|<关键字段>|<章节标题>" "<目标笔记>"
最终回复说明：
- 已写入的目标文件。
- 写入/更新了哪些口径。
- 验证方式。
- 如果有代码仓未提交脏改，说明没有触碰它们。
适配示例
用户说：“将现在的大屏字段计算逻辑更新到 Obsidian 里的个人功能开发说明里。”
执行要点：
- 在代码中核对大屏 controller、service、Mapper、前端 API。
- 在项目资料中找到对应项目的
个人功能开发说明.md。 - 识别已有字段表和“重点关注字段”格式。
- 草拟“当前实现口径”和表格更新。
- 先预览目标路径、章节、改动摘要，等确认后写入。
用户说：“把这个接口字段的取值方式补到项目资料。”
执行要点：
- 先从接口入口追到返回字段的真实赋值点。
- 核对字段名、类型、来源表、枚举、过滤条件和空值处理。
- 找到项目资料里对应功能说明或接口说明章节。
- 预览补写内容，确认后写入。