chore: snapshot before P0 security phase (backup point)
This commit is contained in:
SpecialX
@@ -4,19 +4,23 @@
|
||||
|
||||
**任何任务开始前，必须先查阅架构影响地图，通过图定位代码和模块。**
|
||||
|
||||
1. **先图后码**：执行任何分析、修改、搜索任务时，首先阅读 `docs/architecture/004_architecture_impact_map.md` 或 `docs/architecture/005_architecture_data.json`，从图中定位目标模块、函数、依赖关系，再按图索骥读取源码
|
||||
2. **图未覆盖则先补图**：如果发现项目中存在架构图未记录的模块、函数、表、路由等，**必须优先完善架构图信息**，然后再继续后续工作
|
||||
3. **改码必同步图**：对源码的任何修改完成后，必须同步更新 004 和 005 两个架构文档
|
||||
1. **先图后码**：执行任何分析、修改、搜索任务时，首先运行 `npm run arch:scan` 更新 arch.db，再通过 `npm run arch:query` 查询目标模块、函数、依赖关系，结合阅读 `docs/architecture/004_architecture_impact_map.md` 定位架构设计意图，最后按图索骥读取源码
|
||||
2. **图未覆盖则先补图**：如果发现项目中存在 arch.db 未记录的模块、函数、表、路由等，**必须先运行 `npm run arch:scan` 重新扫描**，然后检查 004 是否需要补充
|
||||
3. **改码必同步图**：对源码的任何修改完成后，必须运行 `npm run arch:scan` 更新 arch.db；若架构设计意图有变化，同步更新 004
|
||||
|
||||
### 架构文档清单
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| `docs/architecture/004_architecture_impact_map.md` | 人类可读的架构影响地图 |
|
||||
| `docs/architecture/005_architecture_data.json` | AI 友好格式的结构化数据 |
|
||||
| `docs/architecture/004_architecture_impact_map.md` | 架构设计意图唯一源（人类可读） |
|
||||
| `docs/architecture/006_k12_feature_checklist.md` | 标准功能模块清单 |
|
||||
| `docs/architecture/007_gap_audit_report.md` | 差距审计报告 |
|
||||
| `docs/architecture/audit/01_decoupling_roadmap.md` | 解耦路线图 |
|
||||
| `docs/architecture/008_module_role_mapping.md` | 模块角色映射 |
|
||||
| `docs/architecture/roadmap/` | 长远规划（tech-debt/decoupling/pending-features） |
|
||||
| `docs/architecture/audit/` | 架构审查报告与归档（含已废弃的 005 JSON、004 V1） |
|
||||
| `docs/troubleshooting/known-issues.md` | 已知问题速查（场景→技术映射 + 工作经验日志） |
|
||||
|
||||
> 注：005_architecture_data.json 已废弃归档至 `audit/archive/`，结构化数据查询统一通过 arch.db
|
||||
|
||||
### 需要同步图的场景
|
||||
|
||||
@@ -30,9 +34,23 @@
|
||||
|
||||
### 同步方式
|
||||
|
||||
- 修改 Markdown 文档中对应的模块章节
|
||||
- 修改 JSON 文档中对应的节点（`modules.*.exports`、`permissions`、`dependencyMatrix`、`routes`、`dbTables` 等）
|
||||
- 确保两个文档内容一致
|
||||
- 修改源码后运行 `npm run arch:scan` 更新 arch.db（强制）
|
||||
- 若架构设计意图变化，同步更新 `docs/architecture/004_architecture_impact_map.md`
|
||||
- 若发现新的"场景→技术"映射或工作经验，更新 `docs/troubleshooting/known-issues.md`
|
||||
|
||||
## 架构元数据库规则（arch.db）
|
||||
|
||||
**arch.db 是代码结构唯一源，AI 工作前必须运行 `npm run arch:scan` 更新。**
|
||||
|
||||
1. **arch.db 取代 005 JSON**：模块、函数、调用关系、依赖关系、技术标签查询 arch.db，不手动维护结构化数据文件
|
||||
2. **查询命令**：
|
||||
- `npm run arch:query -- sql "<SQL>"` 自定义 SQL 查询
|
||||
- `npm run arch:query -- module-deps` 查模块依赖
|
||||
- `npm run arch:query -- module-reverse-deps <module>` 查反向依赖
|
||||
- `npm run arch:query -- symbol-refs <symbol>` 查符号引用链
|
||||
- `npm run arch:query -- tech-usage <tag>` 查技术使用
|
||||
- `npm run arch:query -- violations` 查架构违规
|
||||
3. **arch.db 不替代 004**：arch.db 是"代码现状"，004 是"设计意图"，两者互补
|
||||
|
||||
## 编码规范
|
||||
|
||||
@@ -127,7 +145,7 @@ src/modules/[module]/
|
||||
- Layer 2 Semantic（`semantic-light.css` + `semantic-dark.css`）:语义令牌,业务代码唯一引用入口
|
||||
- 模块命名空间（`lesson-preparation.css`）:`--lp-*` 令牌,明暗双份
|
||||
- Tailwind 暴露（`tailwind-theme.css`）:`@theme inline` 将 Semantic 令牌暴露为 `bg-*`/`text-*`/`font-*` 类
|
||||
- **改令牌必同步图**: 修改令牌定义后,同步更新 `docs/architecture/004` 与 `005`
|
||||
- **改令牌必同步图**: 修改令牌定义后,同步更新 `docs/architecture/004_architecture_impact_map.md` 与 arch.db（`npm run arch:scan`）
|
||||
- **ESLint 强制约束**:
|
||||
- `no-restricted-syntax`: 禁止 `#hex` 字面量
|
||||
- `design-tokens/no-hardcoded-fonts`: 禁止 `'Inter'`/`'Fraunces'`/`'JetBrains Mono'` 字面量（单词边界匹配,不影响 `Interval`/`Interactive` 等标识符）
|
||||
@@ -148,32 +166,61 @@ src/modules/[module]/
|
||||
|
||||
## 问题记录规则
|
||||
|
||||
**所有工作完成后，必须将遇到的问题记录到 `docs/troubleshooting/known-issues.md`（速查手册格式）。**
|
||||
**所有工作完成后，必须将遇到的问题记录到 `docs/troubleshooting/known-issues.md`（索引式速查手册）。**
|
||||
|
||||
### 必须记录的场景
|
||||
|
||||
| 场景 | 记录要求 |
|
||||
|------|---------|
|
||||
| 构建报错（dev/build/lint/tsc） | 记录错误现象 + 正确写法 |
|
||||
| 运行时异常（白屏/API 报错/数据加载失败） | 记录错误现象 + 正确写法 |
|
||||
| 框架/库版本兼容问题 | 记录错误现象 + 正确写法 |
|
||||
| 依赖配置问题（serverExternalPackages/webpackIgnore 等） | 记录错误现象 + 正确写法 |
|
||||
| 架构约束违规 | 记录错误现象 + 正确写法 |
|
||||
| 构建报错（dev/build/lint/tsc） | 记录到"全局经验"对应主题分区 |
|
||||
| 运行时异常（白屏/API 报错/数据加载失败） | 记录到"模块经验"对应模块分区 |
|
||||
| 框架/库版本兼容问题 | 记录到"全局经验: Next.js 配置与运行时" |
|
||||
| 依赖配置问题（serverExternalPackages/webpackIgnore 等） | 记录到"全局经验: Next.js 配置与运行时" |
|
||||
| 架构约束违规 | 记录到"全局经验"对应主题分区 |
|
||||
|
||||
### 记录格式
|
||||
|
||||
以**规则表**形式记录，指明正确做法，无需详细解释原因：
|
||||
索引式表格，指明"场景→技术/规则"映射，不写多行代码示例：
|
||||
|
||||
```markdown
|
||||
## 问题分类标题
|
||||
### X.X 主题分区
|
||||
|
||||
| 规则 | 正确写法 | 错误写法 |
|
||||
|------|---------|---------|
|
||||
| 简述规则 | 代码示例 | 代码示例 |
|
||||
| 场景 | 技术/规则 |
|
||||
|------|----------|
|
||||
| 简述场景 | 正确做法（一句话） |
|
||||
```
|
||||
|
||||
### 记录要求
|
||||
|
||||
- **速查手册风格**：只指明方向，不做新手指导
|
||||
- **索引式**：场景→技术/规则映射，不写代码示例和错误示范列
|
||||
- **去重**：同类问题在原条目补充，不重复创建
|
||||
- **可操作**：正确写法需具体到代码示例
|
||||
- **引用架构规则**：架构分层、模块结构等规则引用 004 和 project_rules，不重复
|
||||
- **工作经验日志**：在"工作经验日志"区按时间倒序追加（50 条上限），记录"做了什么/学到什么/下次注意"
|
||||
|
||||
## AI 工作强制流程
|
||||
|
||||
**所有 AI 工作必须遵循此流程，违反即违规。**
|
||||
|
||||
### 阶段 1: 上下文加载
|
||||
|
||||
1. `npm run arch:scan` 更新 arch.db
|
||||
2. `npm run arch:query -- module-deps` 查目标模块依赖
|
||||
3. `npm run arch:query -- symbol-refs <目标函数>` 查调用链
|
||||
4. 阅读 `src/modules/[模块]/README.md` 读模块工作流程
|
||||
5. 查 `docs/troubleshooting/known-issues.md` "模块经验" 分区读相关经验
|
||||
|
||||
### 阶段 2: 执行工作
|
||||
|
||||
1. 按规划执行
|
||||
2. 修改代码后立即运行 `npm run arch:scan` 更新 arch.db
|
||||
3. 运行 `npx tsc --noEmit` 和 `npm run lint` 确保零错误
|
||||
|
||||
### 阶段 3: 经验沉淀（强制，不可跳过）
|
||||
|
||||
1. 在 `docs/troubleshooting/known-issues.md` "工作经验日志" 区追加一条记录：
|
||||
- 日期 + 时间
|
||||
- 模块
|
||||
- 做了什么 + 学到什么
|
||||
2. 若发现新的"场景→技术"映射 → 提炼到对应模块分区
|
||||
3. 若发现新的架构决策 → 更新 004
|
||||
4. 若代码结构变化 → `npm run arch:scan` 确认 arch.db 已更新
|
||||
|
||||
Reference in New Issue
Block a user