chore: 完成v1.2版本迭代与代码清理

本次提交完成了多项清理与规范工作:
1. 移除默认管理员硬编码配置与云同步相关代码
2. 简化前端与MAUI端的配置,关闭静态资源托管以外的冗余功能
3. 清理.gitignore与协调目录,移除临时文件与冗余规则
4. 统一项目命名规范,修正包名与版本号
5. 重构后端数据模型,移除ABP审计字段与云同步相关逻辑
6. 简化WebView配置与系统栏样式,移除不必要的平台检测代码
7. 更新文档与规则文件,完善项目规范与版本记录
This commit is contained in:
ShaoHua
2026-06-15 22:06:58 +08:00
parent 46db04e43e
commit cf96c56bed
70 changed files with 2514 additions and 2092 deletions
+53
View File
@@ -0,0 +1,53 @@
# 智能体记忆与规范同步规则(必须遵守)
> 适用范围:本规则属于 **全局规则**(语义层面跨项目可复用),关注智能体如何维护记忆与同步规范,与具体项目业务无关。
>
> `.trae/` 整体目录结构与各子目录职责见 [.trae/索引.md](../../索引.md),本文件不再重复描述。
## 记忆存储
- 智能体的记忆必须存放在 `.trae/memory` 文件夹中
- 记忆应按对话日期或主题进行组织,便于后续查询和参考
- 记忆内容应包含对话历史、关键决策、重要代码片段和规范调整等信息
- **项目即时状态**(当前实现到哪一步、未完结事项、临时决策快照)应同步写入 `.trae/rules/项目/04-即时状态记忆.md`,便于其他智能体或开发者快速对齐
## 规范同步
- 每次对话中涉及到的语法或规范相关内容,必须同步整理到 `.trae/rules` 目录下的对应文件中
- **通用规范**(注释、文档同步、工单流程、并行冲突)→ 写入 `.trae/rules/全局/`
- **项目专属**(业务命名、架构边界、数据模型、即时状态)→ 写入 `.trae/rules/项目/`
- 若涉及到新的规范或规则,应创建新的规则文件进行记录
- 规范同步应及时、准确,确保规则文件能真实反映当前项目的编码规范和最佳实践
## 文件命名规则(强制)
`.trae/` 下所有子目录中**新增的文件必须沿用 `NN-名称.md` 序号格式**,否则视为不合规:
- **格式**:两位数字 + 连字符 + 中文/英文名称 + `.md`,例如 `08-XXX规范.md`
- **序号取值**:紧接当前目录已有最大序号 +1,不得跳号、不得重复
- **入口/索引文件例外**`.trae/索引.md` 这类目录入口文件不带序号
- **重排禁止**:除非整体重构,否则不得重排已有文件的序号;新增只能追加在末尾
- **同步更新索引**:每次新增文件后,必须在 [.trae/索引.md](../../索引.md) 的对应章节同步追加该文件的链接与一句话职责说明
- **跨目录创建**:在 `coordination/``memory/` 下新增文件时同样适用本规则
### 各子目录当前最大序号速查
| 子目录 | 当前最大序号 | 下一个可用 |
|---|---|---|
| `rules/全局/` | 07 | 08 |
| `rules/项目/` | 04 | 05 |
| `memory/` | 01 | 02 |
| `coordination/` | 02 | 03 |
## 实现要求
- 智能体应定期检查并更新规则文件,确保其与项目实际情况保持一致
- 当发现规范冲突或需要调整时,应及时记录并通知相关人员
- 记忆存储和规范同步应作为智能体的核心功能,贯穿于整个开发过程
## 路径规范
- 所有 Markdown 文档中不应使用绝对路径,应使用相对路径
- 相对路径应以项目根目录为基准,例如 `.trae/memory` 而非绝对路径
- 确保路径格式统一,使用正斜杠 (`/`) 作为路径分隔符,避免使用反斜杠 (`\`)
- 智能体在生成或修改文档时,应自动检查并替换绝对路径为相对路径
@@ -0,0 +1,33 @@
# 记忆存储规范
> 适用范围:本规则属于 **全局规则**(跨项目通用),约束 `.trae/memory/` 的使用方式。
## 存储结构
- 记忆文件应存放在 `.trae/memory` 文件夹中
- 避免使用与日期相关的文件名,使用通用的描述性文件名
- 文件命名采用 `NN-名称.md` 序号格式
- 记忆内容应包含对话历史、关键决策、重要代码片段和规范调整等信息
## 内容规范
- 记忆文件应保持简洁明了,重点记录重要的开发决策和规范变更
- 避免存储冗余信息,只记录对项目有价值的内容
- 定期清理过时的记忆文件,保持存储空间的合理使用
## 与"项目即时状态"的边界
- `.trae/memory/` 偏向**长期保留**的对话产物与决策记录
- `.trae/rules/项目/04-即时状态记忆.md` 偏向**当前快照**(实现进度、未完结事项),更新频率高
- 二者不要重复存放同一份信息;以"是否需要长期沉淀"为判定标准
## memory/ 生命周期
研发工单验收完成后,对 `memory/` 的处理遵循以下原则:
- **追加而非覆盖**:将本次工单中产生的、值得**长期沉淀**的内容(架构决策、关键避坑经验、引入的新依赖与版本)追加到对应文件
- **不存放过程信息**:实现进度、待办勾选、临时决策这些短期信息应留在 [04-即时状态记忆.md](../项目/04-即时状态记忆.md),不进 `memory/`
- **不删长期内容**:除非内容已被证伪或过时,否则不删除既有条目;过时内容用"已废弃 / 已被 XX 取代"的形式保留语义而非物理删除
- **新增文件序号化**:当主题足够独立时新建 `NN-名称.md`(序号紧接当前最大值),并在 [.trae/索引.md](../../索引.md) 的 `memory/` 章节同步追加链接
## 访问权限
- 记忆文件仅供开发团队内部参考使用
- 确保记忆文件中的敏感信息得到适当保护
- 遵循项目的版本控制和代码管理规范
+34
View File
@@ -0,0 +1,34 @@
---
alwaysApply: true
description: 强制项目注释规范(C# / TypeScript):新增或修改代码必须补全必要注释,便于维护与跨平台开发。
---
# 注释规范(必须遵守)
> 适用范围:本规则属于 **全局规则**(跨项目通用),针对 C# / TypeScript / Vue 代码的注释要求。
## 通用
- 新增或修改的代码必须包含足够注释,使"不了解该模块的人"也能理解其职责、边界与关键决策。
- 优先使用 **XML 文档注释**`///`),而不是随意的行内注释。
- 不允许无意义注释(例如"初始化变量""进入方法")。注释必须解释"为什么/约束/边界/副作用"。
- 不允许出现"TODO/FIXME"但无上下文或无处理方案的注释。
## C#.NET / MAUI
- 所有 `public` / `protected`**类、接口、方法、属性** 必须提供 XML 文档注释,至少包含:
- `summary`:一句话说明用途
- 对关键参数/返回值:`param` / `returns`
- 对异常或副作用:在 `summary` 中明确说明(例如会注册系统钩子/会启动后台服务)
-**跨平台逻辑**
- 禁止在同一文件内混写多个平台的大段 `#if` 实现;应优先使用 `partial`、接口与平台目录分离。
- 平台分离后的公共入口处必须说明"平台差异在哪里、默认实现是什么、为什么这么做"。
-**异步/后台任务**
- 必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入。
-**安全/隐私**
- 禁止在日志或注释中输出密钥、Token、用户隐私信息。
## TypeScript / Vue(前端)
- 对导出的函数/类型必须有注释,解释用途与输入输出。
- 对"与后端/MAUI 交互"的协议字段(例如全局变量、事件名)必须注释说明来源与约束。
@@ -0,0 +1,38 @@
---
alwaysApply: true
description: 强制文档同步规范:每次变更代码(如新增功能、修改接口、调整架构等)必须同步更新 README.md 和 docs 目录下的相关文档。
---
# 文档同步规范(必须遵守)
> 适用范围:本规则属于 **全局规则**(跨项目通用)。
## 通用原则
- **代码即文档,文档随代码**:文档不是静态的,它必须真实反映当前代码的状态。
- **及时性**:在提交代码变更的同时(或紧随其后),必须完成相关文档的更新。
- **准确性**:确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。
- **协作友好(局部修改)**:当并行处理多个研发工单/需求时,更新文档应尽量只修改与本工单直接相关的段落/小节,避免对不相关内容做无意义的重排、改写或格式化;如必须调整非关联内容,应拆分为独立的变更说明清楚原因与影响范围。
> 术语澄清:本规范中"研发工单"指编码工作项;项目业务里的"任务/Todo 待办项"是用户域实体,二者不要混淆。详见 [05-研发工单规则.md](./05-研发工单规则.md)。
## 更新范围
- **README.md**
- 如果变更涉及核心功能点(Features)、安装步骤(Installation)、快速开始(Quick Start)或 API 端点(API Endpoints),必须同步更新。
- 变更涉及技术栈调整或项目结构变化时需更新。
- **docs/ 目录文档**
- **接口变更**:若修改了 API,需同步更新 [技术设计文档](docs/技术设计文档.md) 中的接口部分。
- **功能新增/调整**:需在 [产品需求文档](docs/产品需求文档.md) 和 [技术栈与模块](docs/技术栈与模块.md) 中体现。
- **架构/模式变更**:需更新 [技术设计文档](docs/技术设计文档.md)。
- **代码规范**:若引入了新的编码模式或工具,需更新 [代码规范文档](docs/代码规范文档.md)。
- **版本记录**:所有非琐碎的变更必须在 [版本记录.md](docs/版本记录.md) 中添加记录。
## 检查清单
1. [ ] 是否有新增的 API 端点?(更新 README 和技术设计文档)
2. [ ] 是否修改了现有的业务逻辑或数据结构?(更新技术设计文档)
3. [ ] 是否有新增的功能模块?(更新产品需求文档和技术栈说明)
4. [ ] 是否调整了开发环境或依赖?(更新 README)
5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更?
6. [ ] 文档变更是否保持"局部修改",只影响与本工单相关的段落/小节?(避免无关重排/改写)
+129
View File
@@ -0,0 +1,129 @@
# 研发工单同步规则汇总(Dev Work Item Rules
> 适用范围:本规则属于 **全局规则**(跨项目通用),关注智能体如何拆分编码工作。
> ⚠️ 术语澄清(必读)
>
> 本项目存在两类"任务"概念,必须严格区分,避免命名混淆:
>
> | 术语 | 含义 | 适用范围 |
> |---|---|---|
> | **研发工单(Dev Work Item** | 智能体 / 开发者执行的**编码工作项**(拆分需求、并行开发、集成等) | 本规则文档的全部内容 |
> | **Todo 待办项(Todo Item** | Hua.Todo 项目**业务领域**中用户创建的待办事项(数据库实体、API 资源、UI 列表项) | 业务代码、产品需求文档、技术设计文档 |
>
> 本文档中所有"研发工单 / 工单 / 子工单"均指**编码工作项**,与业务侧的 Todo 待办项无关。
> 在代码、文档与对话中,凡涉及编码侧拆分时,**必须使用"研发工单"或"工单"**,禁止再使用"任务"二字以避免与 Todo 待办项混淆。
>
> 业务侧由于历史原因仍保留 `Task` / `SubTask` 等代码标识符(API、实体、UI),这些属于 Todo 待办项语义,**不在本规范替换范围内**。
>
> 本汇总文件是 [06-研发工单拆分规范.md](./06-研发工单拆分规范.md) 与 [07-并行窗口冲突规约.md](./07-并行窗口冲突规约.md) 的对外索引,详细规则以这两份源文件为准。
---
## 一、研发工单拆分规范
### 适用时机
- 当需求需要先通读项目/产品/技术文档再开始实现时,必须先输出**研发工单拆分文档**
### 输出要求
1. **先读完所有相关文档**:包括 `docs/``docs/project/` 下与本次需求相关的内容
2. **先写工单拆分,再动手实现**:研发工单拆分产出是后续执行的入口与对齐依据
3. **新增专属文件夹**:在 `docs/project` 下新建 `研发工单-<主题>-<日期或版本>` 文件夹
4. **可并行工单拆分**:能同步执行的工单必须拆到不同 Markdown 文件中
5. **文件带序号**:按执行顺序编号(`01-xxx.md``02-xxx.md`
### 每个研发工单文件必须包含
- 目标 / 范围(做什么、不做什么)
- 前置条件(依赖哪些结论 / 接口 / 文档)
- 验收标准(可执行的验证点)
- 风险与回滚(如有)
### 子工单完成标记要求
- 子工单完成后,必须在 `00-工单总览.md` 中标注"已完成"
- 维护"待验证表",记录每个子工单的"待验证 / 已验证"状态
---
## 二、并行窗口冲突规约
### 核心原则
1. **先声明后修改**:修改前先声明 Touch List 与共享文件策略
2. **文件所有权唯一**:同一时段内一个文件只能由一个窗口修改
3. **共享文件单点修改**:高耦合 / 共享入口的改动集中到集成窗口完成
4. **绿线优先**:任何可落盘的变更必须保持可编译
### Touch List 要求
- 精确到文件路径
- 标注修改类型(新增 / 小改 / 重构 / 接口变更 / 配置变更)
- 标注是否为共享文件
- 使用相对路径:`src\<module>\<file>`
### 共享文件判定标准(满足其一即为共享)
- 项目入口 / 启动逻辑、依赖注入注册、全局路由
- 公共配置、公共协议与 DTO、公共组件 / 样式
- 解决方案文件(`.sln``.csproj`)、锁文件、全局配置
### Writer 约束
- 非 Writer 窗口不得编辑共享文件
- 非 Writer 只能提供"差异建议"给 Writer 落盘
### 协调目录
固定目录:`.trae\coordination\`
- `01-ownership.md`:文件所有权登记表
- `02-shared-files.md`:共享文件清单(集成窗口维护)
- `handoff\`:差异建议 / 交接说明
- `wip\`:编译中途状态说明
### 编译绿线规则
- 不得提交破坏编译的变更
- 临时隔离手段(按优先级):
1. 新功能先放在新文件中,不在入口路径启用
2. 通过显式开关控制,默认关闭
3. 通过依赖注入分支或特性开关隔离
- 接口演进采用"双写 / 兼容期"策略
---
## 三、推荐文档结构
```
docs/project/研发工单-<主题>-<版本>/
├── 00-工单总览.md # 背景、目标、关键决策、并行分组、待验证表
├── 01-并行工单A.md
├── 02-并行工单B.md
└── 03-串行工单C.md
```
> 注意:上述目录与文件名中的"工单"指**研发工单**,与业务侧 Todo 待办项无关。
---
## 四、检查清单
### 研发工单拆分检查
1. [ ] 是否已阅读完所有相关文档?
2. [ ] 是否在 `docs/project` 下新建了专属文件夹(命名以"研发工单-"开头)?
3. [ ] 是否产出 `00-工单总览.md`
4. [ ] 是否将可并行工单拆分为不同 md 文件?
5. [ ] 是否所有 md 文件都带有连续序号?
6. [ ] 子工单完成后是否在总览中标注"已完成"并更新待验证表?
### 并行冲突检查
1. [ ] 每个研发工单 md 是否已写 Touch List(精确到文件)?
2. [ ] Touch List 中的共享文件是否指定了唯一 Writer?
3. [ ] 是否避免了对共享文件的无意义格式化 / 重排?
4. [ ] 当前改动是否保持可编译(绿线)?
5. [ ] 若涉及接口演进,是否采用兼容期策略?
---
## 五、与业务侧 Todo 待办项的边界
- 代码、注释、提交信息中描述**编码工作**时:使用"研发工单 / 工单 / 子工单"
- 代码、注释、提交信息中描述**业务功能**时:使用"Todo 待办项 / Todo Item / 父子任务(业务实体)"
- 文档命名前缀:
- 编码侧:`研发工单-<主题>-<版本>/`
- 业务侧(如有):遵循 `docs/` 既有命名习惯,禁止使用"研发工单"前缀
- 提交信息示例:
-`feat(todo): 新增 Todo 待办项截止日期字段(研发工单 02-后端模型)`
-`feat: 完成任务 02`"任务"歧义,禁用)
@@ -0,0 +1,57 @@
---
alwaysApply: false
---
# 研发工单拆分输出规范(必须遵守)
> 适用范围:本规则属于 **全局规则**(跨项目通用)。
> ⚠️ 术语澄清:本规范中的「研发工单(Dev Work Item)」专指智能体 / 开发者执行的**编码工作项**,与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。
> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。
> 凡涉及编码侧拆分时,**必须使用「研发工单」或「工单」**,禁止使用「任务」二字以避免与 Todo 待办项混淆。
## 适用时机
- 当需求需要先通读项目/产品/技术文档再开始实现时,必须先输出研发工单拆分文档,再开始写代码或改配置。
## 输出要求
- **先读完所有相关文档**:包括但不限于 `docs/``docs/project/` 下与本次需求相关的内容。
- **先写工单拆分,再动手实现**:研发工单拆分产出是后续执行的入口与对齐依据。
- **新增一个专属文件夹**:在 `docs/project` 下新建一个文件夹存放本次研发工单拆分文档。
- 文件夹命名建议:`研发工单-<主题>-<日期或版本>`(保持可检索、避免与既有文档冲突)。
- **可并行的工单要拆成不同 md**:能同步执行(相互无依赖/弱依赖)的工单,必须拆到不同的 Markdown 文件中,便于并行推进与分工。
- **文件必须带序号**:同一文件夹下的 md 文件按执行顺序编号,序号从小到大。
- 文件名建议:`01-xxx.md``02-xxx.md``03-xxx.md`
- **每个研发工单文件至少包含**
- 目标/范围(做什么、不做什么)
- 前置条件(依赖哪些结论/接口/文档)
- 验收标准(怎么判断完成,包含可执行的验证点)
- 风险与回滚(如有)
- **子工单完成后的标记要求**
- 当任一子工单(例如 `01-*`/`02-*`/`03-*`)完成实现后,必须在对应版本的 `00-工单总览.md` 中同步标注"已完成"。
- 同时必须维护一张"待验证表"(可用 Markdown 表格),对每个子工单给出"待验证/已验证"状态,避免实现完成但验收未闭环。
- **并行冲突规避要求**:当工单会被分发到多个 solo 窗口并行推进时,每个研发工单文件必须额外包含:
- 触碰文件清单(Touch List,精确到文件)
- 共享文件策略(哪些是共享文件、唯一 Writer 是谁、如何与集成窗口对接)
- 编译绿线策略(如何确保阶段性交付不破坏编译)
## 推荐结构(模板)
- `00-工单总览.md`
- 背景与目标
- 关键决策与约束
- 并行分组说明(哪些文件可同步做)
- 待验证表(每个子工单的"待验证/已验证"状态)
- `01-<并行工单A>.md`
- `02-<并行工单B>.md`
- `03-<串行工单C>.md`
## 最小检查清单
1. [ ] 是否确认已阅读完所有相关文档?
2. [ ] 是否在 `docs/project` 下新建了本次专属文件夹(命名以"研发工单-"开头)?
3. [ ] 是否产出 `00-工单总览.md`(或等价总览文件)?
4. [ ] 是否将可并行工单拆分为不同 md 文件?
5. [ ] 是否所有 md 文件都带有连续序号?
6. [ ] 并行工单是否为每个研发工单文件补充了 Touch List/共享文件策略/编译绿线策略?
7. [ ] 子工单完成后,是否在对应版本的 `00-工单总览.md` 标注"已完成",并在"待验证表"里更新状态?
@@ -0,0 +1,115 @@
---
alwaysApply: false
description:
---
# 并行 solo 窗口冲突规约(必须遵守)
> 适用范围:本规则属于 **全局规则**(跨项目通用)。
> ⚠️ 术语澄清:本规范中的「研发工单(Dev Work Item)」专指智能体 / 开发者执行的**编码工作项**,与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。
> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。
> 凡涉及编码侧拆分时,**必须使用「研发工单」或「工单」**,禁止使用「任务」二字以避免与 Todo 待办项混淆。
## 适用范围
- 当同一个版本/需求被拆分为多个并行研发工单,并由多个 solo 窗口同时推进时适用。
- 目标是同时降低两类风险:
- **文件冲突**:多人同时改同一文件/相邻行导致冲突。
- **编译区间冲突**:A 窗口引入的未完成变更破坏编译,阻塞 B 窗口集成与验证。
## 核心原则
- **先声明后修改**:任何代码改动前,先在研发工单文档中声明"触碰文件清单(Touch List"与"共享文件策略"。
- **文件所有权唯一**:同一时段内,一个文件只能被一个窗口作为"写入者(Writer"修改。
- **共享文件单点修改**:涉及高耦合/共享入口的改动,集中到一个"集成窗口(Integrator)"完成,其他窗口只做准备工作(新文件/独立模块/文档/测试)。
- **绿线优先(可编译)**:任何可落盘、可合入的变更必须保持可编译;临时状态必须通过"隔离手段"而不是破坏编译来实现。
## Touch List(触碰文件清单)
- 每个并行研发工单 md 必须在开头包含一个明确的 Touch List,至少包含:
- 新增/修改/删除的文件路径(精确到文件,必须写"准确目录")
- 预期修改类型(新增/小改/重构/接口变更/配置变更)
- 是否为共享文件(是/否)
- Touch List 必须保持可检索与可更新:变更范围扩大时,必须先更新 Touch List 再改代码。
### 目录书写要求(必须遵守)
- Touch List 内每一条必须使用以下两种格式之一:
- **仓库相对路径(推荐)**`src\<module>\<file>`
- **绝对路径(可选)**`<repo-root>\src\<module>\<file>``<repo-root>` 为本机仓库根目录)
- Touch List 禁止包含构建产物与临时目录中的文件(这些文件不应被手工修改,且极易产生冲突),包括但不限于:
- `**\bin\**``**\obj\**`
- `**\node_modules\**`
- `**\.vite\**``**\dist\**`
### Touch List 模板(复制即可用)
- Touch List:
- `src\<module>\<file>`(共享:否|Writer:本窗口)
- `src\<module>\<file>`(共享:是|Writer<窗口名>
- `docs\<file>`(共享:是/否|Writer<窗口名>
- `.trae\<file>`(共享:是|Writer<窗口名>
## 文件所有权与共享文件策略
- **默认规则**Touch List 中标记为"共享文件"的条目,必须指定唯一 Writer。
- **Writer 约束**
- 非 Writer 窗口不得编辑该共享文件(包括格式化、重排 import、无关重构)。
- 需要对共享文件提出修改时,非 Writer 只能提供"差异建议"(文字说明/伪代码/小片段)交给 Writer 落盘。
- **共享文件判定(满足其一即为共享)**:
- 项目入口/启动逻辑、依赖注入注册、全局路由/导航、公共配置、公共协议与 DTO、公共组件/样式、跨模块公共工具
- 解决方案/项目文件(如 `.sln``.csproj`)、锁文件、全局配置文件(如 `appsettings*`、构建脚本)
## 协调目录(必须遵守)
- 为了让"文件冲突"和"编译中途状态"可操作、可对齐,仓库内必须固定保留一个专用协调目录:
- `.trae\coordination\`
- 该目录只用于协作对齐,不承载业务实现代码;多人可在不同文件中写入,避免互相踩踏。
- 并行推进时必须使用该目录中的文件记录"谁在改什么"和"中途状态怎么保证不破坏编译":
- `.trae\coordination\01-ownership.md`:文件/目录所有权(Writer)登记表
- `.trae\coordination\02-shared-files.md`:本阶段共享文件清单(只有 Integrator 维护)
- `.trae\coordination\handoff\`:非 Writer 提交的差异建议/交接说明(Integrator 落盘)
- `.trae\coordination\wip\`:编译中途状态说明(为什么需要隔离、如何保证绿线、何时收敛)
## 目录分区与低冲突写法
- 优先通过"新增文件"完成并行开发,减少在同一文件内的交错修改。
- 需要扩展既有逻辑时,优先选择低冲突策略:
- C#:新增类/partial 文件、扩展方法、接口实现分文件、平台目录分离
- TypeScript/Vue:新增模块/组件文件,避免在同一大文件内做多处改动
- 禁止在非必要情况下对共享文件做纯格式化、纯重排或无收益重构(这些改动高度易冲突且难以 review)。
## 编译绿线(避免编译区间冲突)
- **不得提交/合入破坏编译的变更**:包括缺失类型、未实现接口、引用不存在、配置缺项导致启动失败等。
- **允许的临时隔离手段(按优先级)**:
1. 新功能先放在新文件/新类中,不在入口路径上启用
2. 通过显式开关控制启用(配置/运行时开关),默认关闭
3. 通过依赖注入分支注册或特性开关隔离,默认不触发
- 当必须进行接口演进时,采用"双写/兼容期"策略:
- 先新增(保持旧接口可用)→ 再迁移调用方 → 最后清理旧接口
## 合入顺序与集成职责
- 每个并行阶段必须明确一个集成窗口(Integrator),负责:
- 处理共享文件的实际落盘与冲突消解
- 保持主干/集成分支持续可编译、可运行
- 其他窗口提交的成果应尽量以"新增文件 + 最小修改点"的方式交付,降低集成成本。
## 任务验收后 coordination 清理
研发工单验收完成、并行阶段结束后,**Integrator 必须**对 `.trae/coordination/` 做收尾清理:
- **清空记录行**:将 `01-ownership.md``02-shared-files.md` 中的运行时记录行删除,仅保留文件顶部说明、表头与示例占位行(让下一轮并行可以直接复用)
- **归档 handoff/wip**:删除已落盘消化掉的 `handoff/``wip/` 内容;如有需要长期沉淀的关键决策,迁移到 [.trae/memory/](../../memory) 对应文件中
- **不删除文件本身**`00-README.md``01-ownership.md``02-shared-files.md` 三个常驻文件保留,仅清空内容
- **冲突收尾确认**:清理前确保所有共享文件已合入主干、Touch List 已不再被任何窗口引用
- **同步项目状态**:在 [.trae/rules/项目/04-即时状态记忆.md](../项目/04-即时状态记忆.md) 的"工单状态快照"中将相关工单标记为已验证
## 最小检查清单
1. [ ] 每个研发工单 md 是否已写 Touch List(精确到文件)?
2. [ ] Touch List 中的共享文件是否指定了唯一 Writer?
3. [ ] 是否避免了对共享文件的无意义格式化/重排?
4. [ ] 当前改动是否保持可编译(绿线)?
5. [ ] 若涉及接口演进,是否采用兼容期策略而非一次性破坏式变更?