AIGC标识 AI开发C#桌面程序项目交接文档

这是一份给 AI 读的项目上下文文档，放在仓库 docs/ 下，随代码一起维护。
无论下次继续开发的是当前这个 AI，还是另一个 AI（换账号、换模型、换工具），都应先读本文档再动代码。

使用规则：

  1. 每次开始新会话，先读本文档和项目规则文件，复述理解，确认后再改代码。
  2. 每次改动完成后，更新对应章节，并在「十五、变更日志」追加一条。
  3. 文档只描述事实与约定。密钥、密码、序列号不写入文档，只写存放位置。
  4. 带 [待填] 的位置按实际情况填写；没有就写"无"。

一、项目概况

项目 内容
项目名称 [待填]
业务背景 / 使用场景 [待填]
当前版本 [待填，如 v1.0.0]
当前状态 [待填：已交付 / 维护中 / 迭代中]
目标用户与部署规模 [待填，如单机 / 多台 / 内网集中部署]
项目所有者 [待填]

二、技术栈与版本

项目 内容
UI 框架 [待填：WinForms / WPF / WinUI]
.NET 版本 [待填：.NET Framework 4.x / .NET 6 / 8]
Visual Studio 版本与工作负载 [待填]
架构模式 [待填：MVVM / 分层 / 其他]
数据库及版本 [待填]
数据访问 [待填：EF Core / Dapper 等]
日志框架 [待填：NLog / Serilog / log4net]
主要 NuGet 包（含版本） [待填]
第三方控件 / 硬件 SDK / 驱动 [待填，注明私有 DLL 位置与授权到期时间]

三、解决方案结构

  • 解决方案文件：[待填].sln　启动项目：[待填]
项目 职责 依赖
[待填：UI] 界面与交互 [待填]
[待填：业务层] 业务逻辑 [待填]
[待填：数据访问] 数据读写 [待填]
[待填：公共库] 通用工具与模型 [待填]
  • 与初始约定不一致的地方：[待填]

四、开发约定与规则（AI 必须遵守）

  • 架构与分层约定：[待填，如 View 不直接访问数据层、业务逻辑放在 Service 层]
  • 命名与目录规范（命名空间、文件夹、资源、样式）：[待填]
  • 异常与日志约定：[待填]
  • 线程与 UI 约定（如耗时操作必须异步、不得阻塞 UI 线程）：[待填]
  • 禁止事项：
    • 不擅自重构既有结构；需要大改先说明理由和影响范围
    • 不覆盖「十三、人工修改记录」中的代码
    • 不删除或改写已有数据库字段，结构变更必须同时提供升级脚本
    • 不把密钥、密码、真实连接串写入代码或文档
  • 项目规则文件（如 CLAUDE.md、AGENTS.md）位置：[待填]

五、环境搭建与运行

  1. 安装 Visual Studio [待填] 及工作负载 [待填]、.NET SDK [待填]
  2. 还原 NuGet 包（私有源：[待填]）
  3. 放入本地依赖：[待填：私有 DLL、硬件 SDK 路径]
  4. 初始化数据库：执行 [待填].sql；测试数据：[待填]
  5. 复制配置示例并填写：[待填]
  6. 启动项目：[待填：启动项目、调试参数]
  7. 走通的主流程（用于验证环境正常）：[待填]

配置项说明（App.config / appsettings.json）

配置项 含义 示例值
[待填] [待填] [待填，只写示例值]

六、构建与发布

  • 编译发布命令 / VS 操作步骤：[待填]
  • 打包方式：[待填：ClickOnce / MSI（WiX）/ Inno Setup / MSIX]，打包工程位置：[待填]
  • 代码签名：证书位置 [待填]，有效期 [待填]（密码不写入）
  • 版本号规则与升级方式：[待填]
  • 自动更新机制：服务器地址 [待填]，更新包格式 [待填]
  • 发布产物归档位置：[待填]
  • 运行环境要求：操作系统 [待填]；运行时 [待填]；VC++ 库等 [待填]；是否需管理员权限 [待填]；分辨率 / DPI 要求 [待填]

七、数据库与数据文件

  • 初始化脚本：[待填]　升级脚本目录与命名规则：[待填]
  • 表结构 / ER 图位置：[待填]
  • 本地数据文件位置（SQLite 文件、缓存、用户配置目录）：[待填]
  • 备份与恢复方式：[待填]

八、外部接口与硬件通讯

对接对象 方式 协议 / 文档位置 注意事项
[待填] HTTP / WebService / 串口 / USB / 其他 [待填] [待填]

九、功能清单与业务规则

模块 功能 状态 关键业务规则 / 限制
[待填] [待填] 已完成 / 部分完成 / 未做 [待填]

十、关键设计决策

AI 写的代码通常只有结果，没有理由。每个重要决策记一条：

决策 原因 备选方案及放弃理由
[待填：如选用 WPF 而非 WinForms] [待填] [待填]
[待填：如数据访问方式、分层方式] [待填] [待填]

十一、验证情况

  • 已人工测试通过：[待填]
  • AI 生成但尚未验证：[待填]
  • 真机测试（打印、串口、读卡器、不同分辨率与 DPI、不同 Windows 版本）：[待填]
  • 自动化测试 / 回归测试清单位置：[待填]

十二、历次开发所用 AI

阶段 / 日期 AI 产品与模型 完成内容
[待填] [待填] [待填]

十三、人工修改记录

这些文件经过人工修改，AI 后续改动时不得覆盖：

文件 修改内容 原因
[待填] [待填] [待填]

十四、已知问题、踩过的坑与待办

踩过的坑

  • [待填：AI 反复写错的地方、绕过的问题、控件或 API 的特殊处理、硬件相关特殊逻辑]

已知问题

问题 影响 优先级 状态
[待填] [待填] 高 / 中 / 低 [待填]

待办与技术债

  • [待填]

十五、变更日志

每次迭代或每次 AI 会话结束后追加一条，最新的放最上面。

日期 版本 执行的 AI 改动内容 涉及文件 验证情况
[待填] [待填] [待填] [待填] [待填] [待填]

十六、账号与资产（只记位置，不记密钥）

资产 用途 归属人 到期 / 续费 凭据存放位置
代码仓库 / CI [待填] [待填] [待填] [待填]
更新服务器 [待填] [待填] [待填] [待填]
代码签名证书 [待填] [待填] [待填] [待填]
第三方服务（短信 / 支付 / 地图等） [待填] [待填] [待填] [待填]
授权文件 / 加密狗 / 测试设备 [待填] [待填] [待填] [待填]

十七、新会话启动提示词（同一 AI 或另一个 AI 通用）

你将继续开发一个已有的 C# 桌面程序，请先阅读，再动手：

1. 阅读 docs/ 下的项目交接文档、项目规则文件，以及数据库和接口文档，
   复述你对项目的理解（技术栈、解决方案结构、架构与命名约定、
   关键设计决策、当前状态），等我确认后再改代码。
2. 严格遵守文档第四部分的约定和禁止事项，不要重构既有结构；
   需要大改时，先说明理由和影响范围，等我同意。
3. 不要覆盖第十三部分列出的人工修改。
4. 涉及打印、串口、读卡器等硬件代码，改动前先说明风险，
   并告诉我需要在真机上验证什么。
5. 每次改动说明：改了哪些文件、为什么、如何验证；
   数据库结构变更必须附升级脚本。
6. 完成后更新交接文档对应章节，并在变更日志追加一条。

本次任务：[待填]

十八、接手自检（新会话开始前做一遍）

posted @ 2026-10-05 19:08  软件那点事  阅读(11)  评论(0)    收藏  举报