feat: 引入 CloudSync 核心能力并新增 Avalonia 桌面端与发布脚本

- 后端:新增 CloudSync 认证/权限/端点/服务与 DTO
- 数据:新增用户/会话/安全策略实体与 EF Core migrations
- 前端:新增云同步设置 UI、客户端与本地存储;Vite 支持 maui 构建输出到 wwwroot
- 桌面端:新增 Avalonia 项目、内置 WebServer、托盘与 Windows 全局热键
- 发布/构建:新增 Windows/Linux 发布脚本与统一入口;调整 MAUI 资源与安装包配置
- 文档:同步更新 README/docs 与协作规则
This commit is contained in:
ShaoHua
2026-04-07 03:34:34 +08:00
parent 18d37fdd24
commit 7a4c516a20
85 changed files with 5774 additions and 127 deletions
@@ -0,0 +1,99 @@
---
alwaysApply: false
description:
---
# 并行 solo 窗口冲突规约(必须遵守)
## 适用范围
- 当同一个版本/需求被拆分为多个并行任务,并由多个 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\ownership.md`:文件/目录所有权(Writer)登记表
- `.trae\coordination\shared-files.md`:本阶段共享文件清单(只有 Integrator 维护)
- `.trae\coordination\handoff\`:非 Writer 提交的差异建议/交接说明(Integrator 落盘)
- `.trae\coordination\wip\`:编译中途状态说明(为什么需要隔离、如何保证绿线、何时收敛)
## 目录分区与低冲突写法
- 优先通过“新增文件”完成并行开发,减少在同一文件内的交错修改。
- 需要扩展既有逻辑时,优先选择低冲突策略:
- C#:新增类/partial 文件、扩展方法、接口实现分文件、平台目录分离
- TypeScript/Vue:新增模块/组件文件,避免在同一大文件内做多处改动
- 禁止在非必要情况下对共享文件做纯格式化、纯重排或无收益重构(这些改动高度易冲突且难以 review)。
## 编译绿线(避免编译区间冲突)
- **不得提交/合入破坏编译的变更**:包括缺失类型、未实现接口、引用不存在、配置缺项导致启动失败等。
- **允许的临时隔离手段(按优先级)**:
1. 新功能先放在新文件/新类中,不在入口路径上启用
2. 通过显式开关控制启用(配置/运行时开关),默认关闭
3. 通过依赖注入分支注册或特性开关隔离,默认不触发
- 当必须进行接口演进时,采用“双写/兼容期”策略:
- 先新增(保持旧接口可用)→ 再迁移调用方 → 最后清理旧接口
## 合入顺序与集成职责
- 每个并行阶段必须明确一个集成窗口(Integrator),负责:
- 处理共享文件的实际落盘与冲突消解
- 保持主干/集成分支持续可编译、可运行
- 其他窗口提交的成果应尽量以“新增文件 + 最小修改点”的方式交付,降低集成成本。
## 最小检查清单
1. [ ] 每个任务 md 是否已写 Touch List(精确到文件)?
2. [ ] Touch List 中的共享文件是否指定了唯一 Writer?
3. [ ] 是否避免了对共享文件的无意义格式化/重排?
4. [ ] 当前改动是否保持可编译(绿线)?
5. [ ] 若涉及接口演进,是否采用兼容期策略而非一次性破坏式变更?
+9 -2
View File
@@ -1,8 +1,6 @@
---
alwaysApply: false
description: 强制任务拆分输出规范:阅读完所有文档后,先产出拆分后的任务 Markdown,并按可并行执行拆分为多个带序号的 md 文件,统一放入 docs/project 下的新建文件夹。
---
# 任务拆分输出规范(必须遵守)
## 适用时机
@@ -23,6 +21,13 @@ description: 强制任务拆分输出规范:阅读完所有文档后,先产
- 前置条件(依赖哪些结论/接口/文档)
- 验收标准(怎么判断完成,包含可执行的验证点)
- 风险与回滚(如有)
- **子任务完成后的标记要求**
- 当任一子任务(例如 `01-*`/`02-*`/`03-*`)完成实现后,必须在对应版本的 `00-任务总览.md` 中同步标注“已完成”。
- 同时必须维护一张“待验证表”(可用 Markdown 表格),对每个子任务给出“待验证/已验证”状态,避免实现完成但验收未闭环。
- **并行冲突规避要求**:当任务会被分发到多个 solo 窗口并行推进时,每个任务文件必须额外包含:
- 触碰文件清单(Touch List,精确到文件)
- 共享文件策略(哪些是共享文件、唯一 Writer 是谁、如何与集成窗口对接)
- 编译绿线策略(如何确保阶段性交付不破坏编译)
## 推荐结构(模板)
@@ -41,3 +46,5 @@ description: 强制任务拆分输出规范:阅读完所有文档后,先产
3. [ ] 是否产出 `00-总览.md`(或等价总览文件)?
4. [ ] 是否将可并行任务拆分为不同 md 文件?
5. [ ] 是否所有 md 文件都带有连续序号?
6. [ ] 并行任务是否为每个任务文件补充了 Touch List/共享文件策略/编译绿线策略?
7. [ ] 子任务完成后,是否在对应版本的 `00-任务总览.md` 标注“已完成”,并在“待验证表”里更新状态?