提示詞:總結這個任務未完成的開發/DEBUG/技術討論/生成辦清單和每個任務的說明,切換到新任務
- __项目愿景 (Vision):__ 如果用一句话来描述这个项目的最终理想状态,它会是什么?答:成为全世界员工做项目简报/工作日报/工作周报/会议记录/起草文件/可交互的深度分析HTML报告的最佳平台,告别传统打字上传发邮件,由AI取代,使员工能真正把时间用在执行而不是做文件工作。
- __问题陈述 (Problem Statement):__ 我们这个项目主要是为了解决当前市场或用户存在的什么核心痛点?答:要很好的高效的使用大模型自带的界面,需要很强大的提示词和操作,而且不同场景提示词不同,一般员工无法上手,很快就放弃AI当助手,然后不使用这些大模型而使用传统手工报告要上网查一堆资料,做一堆图表,目前市面上的报告工具过于复杂,需要专业分析师才能使用,且生成报告耗时过长。主管看的是结果,速度跟质量都没法跟大模型比,又不会用大模型怎么办?这个就是我们这个平台的价值。
- __目标用户 (Target Audience):__ 我们的核心用户是谁?他们的典型特征是什么?答:不具备“直接”操作大模型平台的一般员工,和不俱备上网查找整理资料产出报告的员工,甚至是具备以上能力,但想让AI代理代工能有更多的时间陪伴家人。
- __核心价值 (Core Value):__ 相比于其他可能的解决方案,我们提供的独特价值是什么?答:用户任意形式文件(录音/上传音频/图片/文件/视频/手写稿/手画稿/帐单任可想得到的)都能在5分钟内获得一份可交互的、深度分析HTML报告。”)
## 核心设计哲学 (Core Design Philosophy)
本蓝图专为**大型、多团队、模块化**的复杂软件项目设计。其核心目标是:
1. **关注点分离 (Separation of Concerns)**:将不同角色(如架构师、产品经理、模块开发者)关心的内容物理隔离,使信息获取更高效。
2. **接口驱动开发 (Interface-Driven Development)**:强调模块间的“API合约”,支持并行开发和高度解耦。
3. **对人与AI双重友好 (Human & AI Friendly)**:结构化的目录和命名不仅方便人类开发者快速理解,也为AI Agent提供了精确的上下文寻址路径,避免了在大型文档库中迷失。
4. **高可扩展性 (High Scalability)**:能够轻松容纳未来新增的模块和文档类型,而不会破坏整体结构的清晰性。
---
## 根目录结构概览 (Root Directory Structure Overview)
所有与开发相关的核心文档都将存放在项目根目录下的 `DEV_README/` 文件夹中。
```
DEV_README/
├── ☛ 00_AI_CONTEXT_SUMMARY.md
├── 1_System_Architecture_and_Global_Standards/
├── 2_Shared_Resources_and_Libraries/
└── 3_Modules_Definitions_and_Interfaces/
```
---
## 详细结构与注解 (Detailed Structure & Annotations)
### `☛ 00_AI_CONTEXT_SUMMARY.md`
* **中文名**: AI上下文核心摘要
* **用途**: 这是专门为AI Agent(我)准备的“速查手册”或“大脑索引”。它不包含具体实现细节,而是提供一个高层级的项目地图。
* **核心内容**:
* 项目一句话描述。
* 主要技术栈列表 (例如: 前端React, 后端Python/FastAPI, 数据库PostgreSQL)。
* 所有核心模块 (`module-xxx`) 的列表及其一句话职责描述。
* 指向关键全局文档的快速链接 (例如: 指向系统架构图、通信协议文档)。
* **维护者**: 项目架构师或技术负责人。
* **重要性**: **最高**。维护好此文件能极大提升AI的协作效率和准确性。
* **内容模板与规范 (Content Template & Specification)**:
为了保证AI能最高效地解析,此文件必须严格遵循以下Markdown格式。
```markdown
# AI 上下文核心摘要 (AI Context Core Summary)
# 最后更新: YYYY-MM-DD HH:MM:SS
## 1. 项目概览 (Project Overview)
- **项目名称**: [您的项目名]
- **一句话描述**: [项目的核心价值主张]
- **项目负责人**: @[负责人姓名]
## 2. 全局技术栈 (Global Tech Stack)
| 分类 (Category) | 技术/工具 (Technology/Tool) | 版本 (Version) | 备注 (Notes) |
| :--- | :--- | :--- | :--- |
| 前端 (Frontend) | | | |
| 后端 (Backend) | | | |
| 数据库 (Database) | | | |
| 缓存 (Cache) | | | |
| 部署 (Deployment)| | | |
## 3. 全局规范与蓝图 (Global Standards & Blueprints)
- **系统架构**: [链接到 1_System_Architecture_and_Global_Standards/20_System_Architecture.md]
- **通信协议**: [链接到 1_System_Architecture_and_Global_Standards/30_Cross-Module_Protocols.md]
- **编码规范**: [链接到 1_System_Architecture_and_Global_Standards/40_Global_Coding_Standards.md]
## 4. 核心模块索引 (Core Modules Index)
| 模块ID (Module ID) | 模块负责人 (Owner) | 一句话职责 (Responsibility) | 关键依赖 (Dependencies) | API文档路径 (API Doc Path) |
| :--- | :--- | :--- | :--- | :--- |
| `module-example-1` | @[姓名] | [模块职责描述] | [依赖的模块或库] | [链接到 3.../module-example-1/10_API_Specification.md] |
| `module-example-2` | @[姓名] | [模块职责描述] | [依赖的模块或库] | [链接到 3.../module-example-2/10_API_Specification.md] |
```
### `1_System_Architecture_and_Global_Standards/` (体系架构与全局规范)
* **中文名**: 体系架构与全局规范
* **用途**: 定义项目的“中央法则”。这里的文件是所有团队成员都必须阅读、理解和遵守的通用准则。它是项目统一性的保证。
* **包含文件**:
* `10_System_Vision_and_Scope.md`: **系统愿景与范围**。定义项目的商业目标、目标用户、核心价值主张以及项目边界(做什什么和不做什么)。这是项目的“北极星”。
* `20_System_Architecture.md`: **系统架构蓝图**。包含高层架构图,描绘所有模块如何组合成一个整体,以及关键的数据流、技术选型决策和理由。这是项目的“骨架”。
* `30_Cross-Module_Protocols.md`: **跨模块通信协议**。**极其关键**。定义模块间交互的“法律”,如API风格(RESTful/GraphQL)、数据交换格式(JSON Schema)、统一的错误码、认证授权机制等。
* `40_Global_Coding_Standards.md`: **全局编码规范**。定义通用的代码风格、命名约定、日志规范、分支策略等。各模块可在此基础上扩展,但不能违背。
* `50_Development_Lifecycle.md`: **开发生命周期**。描述从需求提出到功能上线所需经历的完整流程,包括开发、代码审查、测试、集成和部署的步骤。
### `2_Shared_Resources_and_Libraries/` (共享资源与库)
* **中文名**: 共享资源与库
* **用途**: 管理那些被多个模块共同依赖的资产,避免重复造轮子。
* **包含文件**:
* `10_Shared_Libraries_List.md`: **共享库列表**。列出并介绍项目内部开发的、被多个模块复用的代码库(例如:一个通用的数据访问层、一个自定义的UI组件库)。
* `20_Design_System.md`: **设计系统规范**。如果项目包含前端UI,这里将定义统一的视觉风格、颜色、字体、图标和可复用UI组件库的使用方法。
### `3_Modules_Definitions_and_Interfaces/` (模块定义与接口)
* **中文名**: 模块定义与接口
* **用途**: 这是项目主体,体现了“模块化”思想。每个子目录代表一个可独立开发、部署和维护的功能模块。这是并行开发的基石。
* **结构**:
```
3_Modules_Definitions_and_Interfaces/
├── module-user-center/ (用户中心模块)
│ ├── README.md
│ ├── 10_API_Specification.md
│ ├── 20_Internal_Design.md
│ └── 30_Testing_Strategy.md
│
├── module-payment-gateway/ (支付网关模块)
│ └── ... (遵循相同结构)
```
* **模块内文件详解**:
* `README.md`: **模块概述**。包含模块负责人、一句话职责描述、当前状态等。是进入一个模块的“第一扇门”。
* `10_API_Specification.md`: **API接口说明书**。**模块的交付成果**。以OpenAPI/Swagger等标准格式,精确定义该模块向外界提供的所有API接口、数据模型、事件等。这是模块间的“合约”,也是前后端/服务间联调的依据。
* `20_Internal_Design.md`: **内部详细设计**。描述模块内部的实现逻辑、数据库表结构、核心算法、缓存策略等。这部分内容对其他模块是“黑盒”,只有本模块的开发者需要关心。
* `30_Testing_Strategy.md`: **测试策略**。说明该模块的单元测试、集成测试、端到端测试的方案和覆盖范围要求。
---
## 工作流示例 (Workflow Example)
**场景**: 为“用户中心模块”增加一个“修改用户头像”的新功能。
1. **产品经理**: 在 `1_System_Architecture_and_Global_Standards/10_System_Vision_and_Scope.md` 中确认该功能符合项目范围。
2. **架构师**: 在 `3_Modules_Definitions_and_Interfaces/module-user-center/10_API_Specification.md` 中增加一个新的API端点 `PUT /users/{id}/avatar`,并定义好请求体和响应。
3. **前端开发者 & 后端开发者**: 并行开工。
* 后端开发者根据API规范,在 `module-user-center` 模块内部实现业务逻辑,并编写单元测试。
* 前端开发者根据API规范,开发上传头像的UI界面,并使用Mock Server进行调试。
4. **集成**: 前后端开发完成后,根据 `1_System_Architecture_and_Global_Standards/50_Development_Lifecycle.md` 中定义的流程进行集成测试和部署。
5. **AI Agent (我)**: 在整个过程中,当我需要帮助时,我会首先查阅 `00_AI_CONTEXT_SUMMARY.md`,然后根据任务精确跳转到 `module-user-center` 目录下的相关文档来获取上下文,而不会被其他模块的信息干扰。
# 数据访问与处理核心规则 (Data Access & Handling Core Rules)
## **首要原则:永远验证数据结构 (Always Verify Data Structures)**
本规则旨在杜绝因错误假设数据结构而导致的运行时错误,特别是针对数组和对象的操作。这是从 `v0.1.8` 后端重构任务中吸取的关键教训。
---
## **具体条例**
### **1. 数据库查询结果处理规则**
- **强制规则**: 所有通过 `node-postgres` (pg) 库执行的SQL查询,其返回的 `rows` 属性**必须**被视为一个**数组 (Array)**,即使你预期查询只返回一行数据。
- **操作规范**:
- 当需要从一个期望返回单行结果的查询中获取数据时(例如 `... RETURNING *` 或 `SELECT ... WHERE id = ...`),**必须**通过索引 `[0]` 来访问该行数据,然后才能对其进行解构赋值或属性访问。
- 在访问 `rows[0]` 之前,推荐进行存在性检查 (`if (rows.length > 0)`),以处理未找到数据的情况。
- **错误示例 (严禁使用)**:
```typescript
// 错误:直接对 rows 数组进行对象解构
const { id, name } = rows; // 这将导致 id 和 name 为 undefined
```
- **正确示例 (必须遵循)**:
```typescript
// 正确:先通过索引 [0] 获取第一个元素(即那一行数据)
if (rows.length > 0) {
const { id, name } = rows[0];
// ... 后续操作
}
```
### **2. 数组型数据源的索引规则**
- **强制规则**: 当一个变量或函数返回值是一个数组,而你的逻辑需要的是其中**一个特定**的元素时,**必须**使用确切的索引(如 `[0]`)来获取该元素。
- **操作规范**:
- **严禁**将整个数组变量作为另一个对象的属性访问器(即键或索引)。
- **背景案例**:
在使用 `xlsx` 库解析Excel文件时,`workbook.SheetNames` 返回的是一个包含所有工作表名称的**字符串数组**,例如 `['Sheet1', 'Sheet2']`。
- **错误示例 (严禁使用)**:
```typescript
// 错误:将一个数组 ['Sheet1', 'Sheet2'] 作为对象 workbook.Sheets 的键
const worksheet = workbook.Sheets[workbook.SheetNames]; // 这将返回 undefined
```
- **正确示例 (必须遵循)**:
```typescript
// 正确:明确使用索引 [0] 来获取第一个工作表的名称,然后用该名称字符串作为键
const firstSheetName = workbook.SheetNames[0];
const worksheet = workbook.Sheets[firstSheetName];
```
---
## **目的与收益**
- **消除低级错误**: 从根源上杜绝因混淆数组与对象而导致的 `undefined` 错误和类型错误。
- **提升代码健壮性**: 强制进行边界检查(如 `rows.length > 0`),使代码能优雅地处理“未找到”等正常业务场景。
- **提高代码可读性**: 使代码意图更加明确,任何阅读者都能清楚地知道代码正在操作的是数组中的单个元素。
当出现Unexpected API Response: The language model did not provide any assistant messages. This may indicate an issue with the API or the model's output. 时马上压缩就对了