本文定义江斌知识库的统一入口、目录归属、文档要求和发布流程。以后项目中的业务文档、技术方案、问题复盘、发布手册、工作总结和架构设计，默认沉淀到 jb2ai.ltd；项目仓库只保留必须随代码版本发布的文档。

1. 统一入口

  • 线上知识地图：https://jb2ai.ltd/
  • 本地文档源：/Users/zhoujiangbin/code/docker-dev-env/www/tengxunyun/work/team-manage-local/interview_docs
  • 站点应用：/Users/zhoujiangbin/code/docker-dev-env/www/tengxunyun/work/team-manage-local
  • 发布脚本：/Users/zhoujiangbin/code/docker-dev-env/www/tengxunyun/scripts/team-manage-fast-publish.sh

首页会自动读取 Markdown 文件，生成项目空间、任务入口、知识分层、最近更新和正文全文索引。新增普通文档不需要手工维护首页卡片。

2. 文档分区

分区适合内容默认子目录
12_DGJ2业务梳理DGJ2 业务、状态、表、接口、MQ、排查专题按现有编号继续维护
13_项目文档项目总览、业务模块、需求方案、实现和交付记录<项目名>/
14_研发经验与问题复盘故障根因、排查过程、技术决策、兼容经验<项目名>/
15_发布运维与排查手册发布步骤、DDL、配置、脚本、补偿和验证<项目名>/
16_工作总结与述职日报、周报、月报、阶段总结和述职证据<年份>/
17_架构_API与数据设计架构图、API 契约、表结构、状态机、消息设计<项目名>/

3. 每篇文档必须回答的问题

  1. 这是什么业务或问题，为什么需要处理？
  2. 入口文件、核心 Service、表、状态和外部系统在哪里？
  3. 正常流程和异常流程分别是什么？
  4. 如何排查和验证，使用哪些 SQL、日志或命令？
  5. 修改时有哪些风险，回归范围是什么？
  6. 哪些结论已验证，哪些仍是待确认项？

4. 文件命名

  • 项目长期文档：NN_主题.md，例如 01_订单同步业务总览.md。
  • 复盘和报告：YYYY-MM-DD_主题.md，例如 2026-07-15_库存不一致问题复盘.md。
  • 同一需求的发布动作集中在一篇 runbook 中，不把 DDL、配置、脚本和验证步骤拆散。
  • 标题和文件名使用具体业务名，避免“临时记录”“问题整理”等无法搜索的名称。

5. 文档元数据

新文档优先在文件顶部声明元数据，让知识地图准确知道“属于哪个项目、是什么经验、是否已验证、下一步怎么用”：

---
project: dgj2
type: retrospective
status: verified
tags: [库存, 采购入库, 重复单据]
updated_at: 2026-07-15
next_steps: [先按业务单号核对主表与明细, 再核对库存流水和实时库存, 修复后补充回归结果]
---

字段约定：

字段可选值或格式用途
projectdgj2、saas-dgj、knowledge-base、local-dev、engineering、career进入对应项目经验空间
typeproject、business、design、retrospective、runbook、report、learning进入理解、设计、排查、发布或总结任务入口
statusmaintained、verified、draft、needs_review、deprecated区分持续维护、已验证、草稿、待复核和已废弃
tagsYAML 行内数组补充业务名、接口、表、故障现象和技术关键词
updated_atYYYY-MM-DD首页和项目页的最近更新排序
next_stepsYAML 行内数组在文章页显示读完后可执行的动作

旧文档没有元数据时，站点会按目录和文件名推断，不阻断展示；被再次修改或复用时应补齐元数据。

6. 知识地图使用路径

  1. 按目标开始：先选择理解业务、设计方案、排查问题、发布运维或总结成果。
  2. 按项目聚合：进入项目空间，查看该项目的所有业务、设计、复盘和执行手册。
  3. 全文定位细节：使用业务名、异常现象、API、表名、类名、状态或命令搜索正文。
  4. 从文章继续行动：按“读完后的下一步”和“关联经验”进入执行或补充文档。
  5. 把结果沉淀回来：更新状态、验证证据、日期和下一步，形成闭环。

7. 发布与验证

普通 Markdown 变更使用：

/Users/zhoujiangbin/code/docker-dev-env/www/tengxunyun/scripts/team-manage-fast-publish.sh docs

修改渲染器、路由、模板或知识分类元数据时使用：

/Users/zhoujiangbin/code/docker-dev-env/www/tengxunyun/scripts/team-manage-fast-publish.sh app

发布后至少验证首页、项目页、所属分类和新增文章均返回 200，并确认首页搜索能使用项目名、业务名、接口名、表名、类名或故障关键词命中文档。手机端还要确认无横向溢出，文章表格位于可横向滚动容器中。

8. 边界

  • 密码、Token、Cookie、生产凭据、完整环境变量值和客户敏感数据禁止进入网站。
  • 原始 Codex 对话、原始日志和个人隐私材料保留在本机；网站只保存脱敏后的结论、流程和证据摘要。
  • 已存在于 ~/.codex/work-docs 的旧文档暂时作为历史资料，后续被更新或复用时迁入网站，不再把新工作文档默认写入旧目录。