Initialize harness coding docs
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# AI 开发入口
|
||||
|
||||
> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
|
||||
|
||||
## 一句话定位
|
||||
|
||||
【项目名】是【一句话说明项目目标、用户和 MVP 范围】。
|
||||
|
||||
第一版 MVP 只做：【列出最小闭环功能】。
|
||||
|
||||
## 必读顺序
|
||||
|
||||
每次开始写代码前，按这个顺序建立上下文：
|
||||
|
||||
1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
|
||||
2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
|
||||
3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
|
||||
4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
|
||||
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
|
||||
6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
|
||||
7. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
|
||||
|
||||
如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。
|
||||
|
||||
## 当前阶段
|
||||
|
||||
当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。
|
||||
|
||||
优先路径：
|
||||
|
||||
1. Phase 0：最小可运行地基。
|
||||
2. Phase 1：最高风险功能原型。
|
||||
3. Phase 2：核心用户流程。
|
||||
4. Phase 3：账号 / 数据持久化 / 同步。
|
||||
5. Phase 4：部署、离线、监控或上线准备。
|
||||
|
||||
## 领取任务规则
|
||||
|
||||
从 [`06-tasks.md`](06-tasks.md) 领取任务时：
|
||||
|
||||
- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
|
||||
- 开始前把该任务状态改为 `DOING`。
|
||||
- 本轮只完成这一个任务。
|
||||
- 验收通过后把状态改为 `DONE`。
|
||||
- 做完即停，汇报验证结果，等待下一步指令。
|
||||
|
||||
如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
|
||||
|
||||
## MVP 边界
|
||||
|
||||
MVP 只做：
|
||||
|
||||
- 【P0 功能 1】
|
||||
- 【P0 功能 2】
|
||||
- 【P0 功能 3】
|
||||
|
||||
MVP 不做：
|
||||
|
||||
- 【明确非目标 1】
|
||||
- 【明确非目标 2】
|
||||
- 【后续版本功能】
|
||||
|
||||
## 事实来源
|
||||
|
||||
项目事实只信：
|
||||
|
||||
- 【业务数据源 / schema / seed 数据路径】
|
||||
- 【产品需求文档】
|
||||
- 【接口合约】
|
||||
- 【现有代码中的权威模块】
|
||||
|
||||
不要把以下内容当事实来源：
|
||||
|
||||
- 历史备份文件。
|
||||
- 旧导出文档。
|
||||
- 临时实验目录。
|
||||
- 未被任务或需求引用的草稿。
|
||||
|
||||
## 常见任务该看哪里
|
||||
|
||||
做页面 / UI：
|
||||
|
||||
- 先看 `02-requirements.md` 的对应验收标准。
|
||||
- 再看 `routes.md` 的页面职责。
|
||||
- 最后看 `04-architecture.md` 的组件边界。
|
||||
|
||||
做后端 API：
|
||||
|
||||
- 先看 `api.md` 的接口合约。
|
||||
- 再看 `04-architecture.md` 的数据模型和鉴权边界。
|
||||
|
||||
做数据模型：
|
||||
|
||||
- 先看 `04-architecture.md` 的数据模型。
|
||||
- 如果 schema 变化，必须同步更新 `api.md`、`current-state.md` 和相关任务验收。
|
||||
|
||||
做部署 / 运行：
|
||||
|
||||
- 先看 `03-tech-stack.md` 的运行命令。
|
||||
- 再看 `current-state.md` 的当前真实命令。
|
||||
|
||||
## 验证命令
|
||||
|
||||
把本项目真实命令填在这里：
|
||||
|
||||
```bash
|
||||
# 示例
|
||||
npm test
|
||||
npm run build
|
||||
go test ./...
|
||||
pytest
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 改前端后跑：【命令】。
|
||||
- 改后端后跑：【命令】。
|
||||
- 改数据结构后跑：【命令】。
|
||||
- 如果命令当前不可运行，必须在回复里如实说明原因。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 项目愿景
|
||||
|
||||
## 一、核心目标
|
||||
|
||||
【项目名】要解决：【一句话说明用户的真实问题】。
|
||||
|
||||
> 让【目标用户】能够【完成核心任务】，并获得【明确价值】。
|
||||
|
||||
它不是【容易混淆的产品类型】，而是一个为【核心场景】服务的工具。
|
||||
|
||||
## 二、目标用户
|
||||
|
||||
- 【用户类型 1】：【典型需求】
|
||||
- 【用户类型 2】：【典型需求】
|
||||
- 【用户类型 3】：【典型需求】
|
||||
|
||||
## 三、产品原则
|
||||
|
||||
遇到取舍时，以这些原则为准：
|
||||
|
||||
- **核心流程优先**：先把用户最常做、最关键的流程做顺。
|
||||
- **真实数据优先**：不造假数据、不虚构字段、不用演示逻辑冒充产品逻辑。
|
||||
- **小步交付**：每一步都能运行、能验证、能回退。
|
||||
- **少即是稳**：MVP 不追求完整，只追求最小闭环可靠。
|
||||
- **可维护**：架构、命名、边界要让后续 agent 能继续接手。
|
||||
|
||||
## 四、核心价值主张
|
||||
|
||||
| 价值点 | 说明 |
|
||||
| --- | --- |
|
||||
| 【价值 1】 | 【用户得到什么】 |
|
||||
| 【价值 2】 | 【用户得到什么】 |
|
||||
| 【价值 3】 | 【用户得到什么】 |
|
||||
|
||||
## 五、不做什么（非目标）
|
||||
|
||||
- 不做【非目标 1】。
|
||||
- 不做【非目标 2】。
|
||||
- 不做【容易膨胀但不属于 MVP 的功能】。
|
||||
|
||||
> MVP 的具体功能范围与验收标准，见 [需求](02-requirements.md)。
|
||||
@@ -0,0 +1,66 @@
|
||||
# 需求
|
||||
|
||||
> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达，**不涉及技术实现**。
|
||||
> 技术方案、数据结构、字段定义见 [架构设计](04-architecture.md)。
|
||||
|
||||
## 一、业务现状
|
||||
|
||||
| 项 | 状态 |
|
||||
| --- | --- |
|
||||
| 用户 | 【目标用户和当前痛点】 |
|
||||
| 数据 | 【已有 / 缺失 / 待清洗的数据】 |
|
||||
| 现有系统 | 【如有，说明当前状态】 |
|
||||
| 约束 | 【版权、合规、性能、设备、网络等限制】 |
|
||||
|
||||
## 二、用户角色
|
||||
|
||||
- **【角色 1】**：【能做什么】
|
||||
- **【角色 2】**：【能做什么】
|
||||
- **游客 / 未登录用户**：【是否允许访问，待定也要写明】
|
||||
|
||||
## 三、功能清单
|
||||
|
||||
### 第一版 MVP（最小闭环）
|
||||
|
||||
| 功能 | 用户能做什么 | 优先级 |
|
||||
| --- | --- | --- |
|
||||
| 【功能 1】 | 【用户动作和结果】 | P0 |
|
||||
| 【功能 2】 | 【用户动作和结果】 | P0 |
|
||||
| 【功能 3】 | 【用户动作和结果】 | P0 |
|
||||
|
||||
### 后续迭代
|
||||
|
||||
| 功能 | 描述 | 阶段 |
|
||||
| --- | --- | --- |
|
||||
| 【功能】 | 【说明】 | V2 |
|
||||
| 【功能】 | 【说明】 | V3 |
|
||||
|
||||
## 四、核心用户故事（MVP）
|
||||
|
||||
1. 作为【角色】，我打开系统后能【第一步】。
|
||||
2. 我可以【关键动作】，并看到【结果】。
|
||||
3. 我可以【继续动作】，系统会【保存 / 同步 / 展示】。
|
||||
4. 当【异常场景】发生时，系统会【降级 / 提示 / 阻止错误】。
|
||||
|
||||
## 五、验收标准（MVP）
|
||||
|
||||
每条 P0 功能对应可验证的判据：
|
||||
|
||||
- **【功能 1】**：【打开 / 点击 / 输入 / 保存 后，应看到什么结果】。
|
||||
- **【功能 2】**：【明确时间、状态、数据持久化或错误处理要求】。
|
||||
- **【功能 3】**：【跨刷新、跨设备、权限、边界情况等要求】。
|
||||
|
||||
## 六、范围边界与决策
|
||||
|
||||
| 问题 | 决策 |
|
||||
| --- | --- |
|
||||
| 第一版平台 | 【Web / 移动端 / 桌面 / CLI】 |
|
||||
| 是否需要账号 | 【是 / 否 / 待定】 |
|
||||
| 第一版范围 | 【最小闭环】 |
|
||||
| 暂不支持 | 【明确排除项】 |
|
||||
|
||||
## 七、待确认 / 风险点
|
||||
|
||||
- 【风险 1】：【为什么有风险，建议先如何验证】。
|
||||
- 【风险 2】：【数据、性能、授权、依赖、体验等风险】。
|
||||
- 【待确认问题】：【谁来决策，什么时候需要决策】。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 技术栈（Tech Stack）
|
||||
|
||||
> “用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 [架构设计](04-architecture.md)。
|
||||
> 未定项必须标为待定，不要让 agent 在代码里自行决定。
|
||||
|
||||
## 一、技术栈一览
|
||||
|
||||
| 维度 | 选型 | 状态 | 理由 / 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 前端框架 | 【例如 React / Vue / go-app / 原生】 | 【已定 / 待定】 | 【理由】 |
|
||||
| UI 样式方案 | 【例如 CSS / Tailwind / 组件库】 | 【已定 / 待定】 | 【理由】 |
|
||||
| 状态管理 | 【例如框架内置 / Zustand / Redux】 | 【已定 / 待定】 | 【理由】 |
|
||||
| 后端 | 【例如 Go net/http / FastAPI / NestJS】 | 【已定 / 待定】 | 【理由】 |
|
||||
| 数据库 | 【例如 SQLite / Postgres / MySQL】 | 【已定 / 待定】 | 【理由】 |
|
||||
| 鉴权方式 | 【例如 Session Cookie / JWT / 无账号】 | 【已定 / 待定】 | 【理由】 |
|
||||
| 部署方式 | 【例如单二进制 / Docker / Vercel】 | 【已定 / 待定】 | 【理由】 |
|
||||
| 测试 | 【例如 go test / pytest / vitest】 | 【已定 / 待定】 | 【理由】 |
|
||||
|
||||
## 二、决策记录与演进
|
||||
|
||||
- 【选型 1】：现在选择【方案】，因为【理由】。未来在【条件】出现时再评估【替代方案】。
|
||||
- 【选型 2】：当前不引入【工具 / 框架】，避免【复杂度】。
|
||||
|
||||
## 三、构建与运行命令
|
||||
|
||||
| 用途 | 命令 |
|
||||
| --- | --- |
|
||||
| 安装依赖 | `【命令】` |
|
||||
| 本地开发 | `【命令】` |
|
||||
| 构建 | `【命令】` |
|
||||
| 测试 | `【命令】` |
|
||||
| 格式化 / 静态检查 | `【命令】` |
|
||||
|
||||
Windows PowerShell 如有差异，单独列出：
|
||||
|
||||
```powershell
|
||||
# 示例
|
||||
npm install
|
||||
npm run dev
|
||||
npm test
|
||||
```
|
||||
|
||||
## 四、依赖纪律
|
||||
|
||||
- 新增第三方依赖前，先说明用途、替代方案和维护成本。
|
||||
- 不确定的技术选型先更新本文，再进入代码。
|
||||
- 不允许同一职责并存两套框架或两套状态管理方案。
|
||||
@@ -0,0 +1,124 @@
|
||||
# 架构设计
|
||||
|
||||
> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。
|
||||
> 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 [技术栈](03-tech-stack.md)。
|
||||
|
||||
## 一、系统结构
|
||||
|
||||
```text
|
||||
用户
|
||||
|
|
||||
v
|
||||
前端 / 客户端
|
||||
|
|
||||
v
|
||||
后端 API
|
||||
|
|
||||
v
|
||||
数据库 / 文件 / 第三方服务
|
||||
```
|
||||
|
||||
把真实组件替换到上图中，例如：
|
||||
|
||||
- 前端：【框架、入口目录】
|
||||
- 后端：【框架、入口文件】
|
||||
- 数据库：【类型、迁移方式】
|
||||
- 外部服务：【支付、邮件、对象存储、AI 服务等】
|
||||
|
||||
## 二、职责划分
|
||||
|
||||
**前端 / 客户端**
|
||||
|
||||
- 【页面与交互职责】
|
||||
- 【客户端状态】
|
||||
- 【本地缓存 / 离线 / 上传等职责】
|
||||
|
||||
**后端**
|
||||
|
||||
- 【鉴权】
|
||||
- 【业务 API】
|
||||
- 【数据校验】
|
||||
- 【异步任务 / 文件处理】
|
||||
|
||||
**数据库 / 存储**
|
||||
|
||||
- 【持久化哪些数据】
|
||||
- 【不持久化哪些数据】
|
||||
- 【哪些数据只读，哪些数据可变】
|
||||
|
||||
## 三、数据模型
|
||||
|
||||
### 3.1 静态 / 只读数据
|
||||
|
||||
| 数据 | 来源 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 【数据名】 | 【路径 / 服务】 | 【字段和约束】 |
|
||||
|
||||
关键事实：
|
||||
|
||||
- 【字段事实 1】
|
||||
- 【字段事实 2】
|
||||
- 【路径映射 / schema 约束】
|
||||
|
||||
### 3.2 用户 / 业务动态数据
|
||||
|
||||
示例表结构：
|
||||
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id INTEGER PRIMARY KEY,
|
||||
email TEXT UNIQUE NOT NULL,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
需要说明：
|
||||
|
||||
- 主键和唯一约束。
|
||||
- 重要索引。
|
||||
- 是否软删除。
|
||||
- 哪些字段由服务端生成。
|
||||
- 哪些字段是前向兼容预留，MVP 是否启用逻辑。
|
||||
|
||||
## 四、关键技术难点
|
||||
|
||||
| 难点 | 说明 | 应对 |
|
||||
| --- | --- | --- |
|
||||
| 【难点 1】 | 【为什么难】 | 【先做 spike / 原型 / 测试】 |
|
||||
| 【难点 2】 | 【为什么难】 | 【降级方案】 |
|
||||
|
||||
高风险功能应先做最小原型，不要等整个系统搭完才验证。
|
||||
|
||||
## 五、推荐开发顺序
|
||||
|
||||
1. 最小可运行地基。
|
||||
2. 最高风险功能原型。
|
||||
3. 核心用户流程。
|
||||
4. 数据持久化和账号体系。
|
||||
5. 完整验收、部署和边界处理。
|
||||
|
||||
## 六、项目结构建议
|
||||
|
||||
```text
|
||||
project/
|
||||
├── docs/
|
||||
├── src/ 或 app/
|
||||
├── server/ 或 api/
|
||||
├── tests/
|
||||
├── scripts/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
按实际技术栈替换：
|
||||
|
||||
- `src/`：【前端 / 客户端代码】
|
||||
- `server/`：【后端代码】
|
||||
- `scripts/`：【数据校验、迁移、构建辅助脚本】
|
||||
- `tests/`：【测试目录】
|
||||
|
||||
## 七、架构纪律
|
||||
|
||||
- 业务事实和 schema 变化必须同步更新本文。
|
||||
- 不在代码里发明文档没有的接口、字段和状态。
|
||||
- 不把静态内容、用户数据、缓存数据混在一个模型里。
|
||||
- 高风险模块先单独验证，再接入完整页面或流程。
|
||||
@@ -0,0 +1,79 @@
|
||||
# 编码规则（Coding Rules）
|
||||
|
||||
> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
|
||||
> 与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；与“该不该做”冲突时，以 [需求](02-requirements.md) 为准。
|
||||
|
||||
## 0. 黄金法则
|
||||
|
||||
1. **不臆造**：数据字段、文件、接口、依赖，不确定就查证或询问。
|
||||
2. **守范围**：只做当前任务要求的事，不顺手加后续功能。
|
||||
3. **照架构**：使用既定技术栈和模块边界，不擅自引入新框架。
|
||||
4. **小步改**：一次只解决一个问题，不夹带无关重构。
|
||||
5. **可验证**：改完必须能构建、能测试、对得上验收标准。
|
||||
|
||||
## 1. 动手前
|
||||
|
||||
- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
|
||||
- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
|
||||
- 先找现有函数、组件、工具和测试，复用优先。
|
||||
- 如果需求含糊，或改动会偏离原则 / 架构，先问。
|
||||
|
||||
## 2. 事实来源纪律
|
||||
|
||||
- 只相信文档指定的权威数据源、schema、API 合约和当前代码。
|
||||
- 不从备份、草稿、旧导出文件里推断当前事实。
|
||||
- 不虚构字段、接口、状态码、配置项。
|
||||
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md` 和相关任务。
|
||||
|
||||
## 3. 范围纪律
|
||||
|
||||
- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
|
||||
- V2 / V3 功能只记录，不实现。
|
||||
- 需求明确排除的非目标不得实现。
|
||||
- 不为“将来可能用到”提前抽象。
|
||||
|
||||
## 4. 架构纪律
|
||||
|
||||
- 技术栈以 `03-tech-stack.md` 为准。
|
||||
- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
|
||||
- 模块职责以 `04-architecture.md` 为准，不跨层偷写逻辑。
|
||||
- API 形状以 `api.md` 为准，页面路由以 `routes.md` 为准。
|
||||
|
||||
## 5. 代码规范
|
||||
|
||||
- 标识符使用英文。
|
||||
- UI 文案、注释、文档语言按项目现状保持一致。
|
||||
- 错误必须处理，不吞错。
|
||||
- 注释解释“为什么”，不复述“做了什么”。
|
||||
- 遵守项目已有格式化工具，不手工制造风格分裂。
|
||||
|
||||
## 6. 测试与验证
|
||||
|
||||
完成前至少检查：
|
||||
|
||||
- [ ] 构建通过。
|
||||
- [ ] 相关测试通过。
|
||||
- [ ] 对得上需求验收标准。
|
||||
- [ ] 没有夹带无关改动。
|
||||
- [ ] 涉及文档事实变化时，文档已同步。
|
||||
- [ ] 回复里如实说明跑了什么命令、结果如何。
|
||||
|
||||
把真实命令填在这里：
|
||||
|
||||
```bash
|
||||
# 示例
|
||||
npm test
|
||||
npm run build
|
||||
go test ./...
|
||||
```
|
||||
|
||||
## 7. 绝不
|
||||
|
||||
- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
|
||||
- 绝不为了让测试通过而删除断言、降低验收标准。
|
||||
- 绝不擅自删除用户已有文件或重置工作区。
|
||||
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
|
||||
|
||||
## 8. 拿不准就问
|
||||
|
||||
问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
|
||||
@@ -0,0 +1,68 @@
|
||||
# 任务看板（Tasks）
|
||||
|
||||
> 把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。
|
||||
|
||||
## 使用规则
|
||||
|
||||
1. **一次只做一个任务**：每轮只领取一个状态为 `TODO`、且依赖均已 `DONE` 的任务，取最靠前的那个。
|
||||
2. **做完即停**：完成该任务、自测通过、把状态改成 `DONE` 后，停下来汇报。
|
||||
3. **不跳步**：依赖未完成的任务不能开工。
|
||||
4. **完成定义**：以 [编码规则](05-coding-rules.md) 的验证清单为准。
|
||||
5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
|
||||
|
||||
## 状态图例
|
||||
|
||||
`TODO` 待开始 · `DOING` 进行中（同一时间最多 1 个）· `DONE` 已完成并验收 · `BLOCKED` 受阻（注明原因）
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 · 地基
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| T-001 | 初始化项目骨架 | - | 依赖安装成功；本地能启动；首页 / 入口可访问 | TODO |
|
||||
| T-002 | 建立基础目录和配置 | T-001 | 目录结构符合 `04-architecture.md`；配置不含密钥 | TODO |
|
||||
| T-003 | 加入最小测试 / 构建检查 | T-001 | 测试命令和构建命令可运行 | TODO |
|
||||
|
||||
## Phase 1 · 最高风险验证
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| T-101 | 验证最高风险功能原型 | T-001 | 用最小输入跑通核心难点，结论写入文档 | TODO |
|
||||
| T-102 | 把原型接入正式结构 | T-101 | 代码进入约定模块，测试覆盖关键路径 | TODO |
|
||||
|
||||
## Phase 2 · 核心用户流程
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| T-201 | 实现核心页面 / 入口 | T-102 | 用户能进入主流程第一步 | TODO |
|
||||
| T-202 | 实现核心动作 | T-201 | 用户能完成 MVP 最关键动作 | TODO |
|
||||
| T-203 | 实现结果展示 / 状态反馈 | T-202 | 用户能看到保存、提交或处理结果 | TODO |
|
||||
|
||||
## Phase 3 · 数据与账号
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| T-301 | 建立数据模型 / 迁移 | T-202 | 表结构符合 `04-architecture.md` | TODO |
|
||||
| T-302 | 实现鉴权 / 权限边界 | T-301 | 未授权访问被拒绝；授权后可访问 | TODO |
|
||||
| T-303 | 实现数据持久化 | T-302 | 刷新 / 重进后数据仍在 | TODO |
|
||||
|
||||
## Phase 4 · 收尾与发布
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| T-401 | 完整验收 MVP | T-303 | `02-requirements.md` 的 P0 验收全部通过 | TODO |
|
||||
| T-402 | 部署 / 打包 / 运行文档 | T-401 | 新环境可按文档运行 | TODO |
|
||||
|
||||
## 里程碑
|
||||
|
||||
- M1：最小可运行地基完成。
|
||||
- M2：最高风险功能已验证。
|
||||
- M3：MVP 核心闭环完成。
|
||||
- M4：可交付 / 可部署。
|
||||
|
||||
## 待办池（Backlog）
|
||||
|
||||
- 【V2 功能 1】
|
||||
- 【V2 功能 2】
|
||||
- 【优化项】
|
||||
@@ -0,0 +1,33 @@
|
||||
# 项目文档导航
|
||||
|
||||
> 复制到新项目后，先替换本文中的项目名称和一句话定位，再逐个补齐后续文档。
|
||||
|
||||
## 一句话定位
|
||||
|
||||
【项目名】是一个【目标用户】使用的【产品类型 / 系统类型】，用于解决【核心问题】，第一版先完成【MVP 闭环】。
|
||||
|
||||
示例：
|
||||
|
||||
> 这是一个面向小团队的工单协作系统，第一版先跑通「提交工单 -> 分派 -> 处理 -> 关闭」闭环。
|
||||
|
||||
## 文档导航
|
||||
|
||||
- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
|
||||
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的仓库级上下文入口。
|
||||
- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
|
||||
- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
|
||||
- [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。
|
||||
- [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
|
||||
- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
|
||||
- [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
|
||||
- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
|
||||
- [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
|
||||
- [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
|
||||
- [当前实现状态](current-state.md)：仓库现实状态、已完成任务、下一步可做任务。
|
||||
|
||||
## 维护原则
|
||||
|
||||
- 需求变化先改文档，再改代码。
|
||||
- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`。
|
||||
- API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
|
||||
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
|
||||
+87
@@ -0,0 +1,87 @@
|
||||
# API 合约
|
||||
|
||||
> 本文定义后端 API 的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。
|
||||
|
||||
如果项目没有后端 API，可改成本地模块接口、CLI 参数或事件合约。
|
||||
|
||||
## 通用约定
|
||||
|
||||
- 传输：【JSON over HTTPS / GraphQL / gRPC / 本地函数调用】。
|
||||
- 鉴权：【Session Cookie / Bearer Token / 无】。
|
||||
- 请求体和响应体编码：【UTF-8 JSON】。
|
||||
- 时间格式：【ISO 8601 / Unix timestamp】。
|
||||
- 未登录访问需要权限的接口时返回：【401 / 403】。
|
||||
|
||||
通用错误响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "bad_request",
|
||||
"message": "请求参数不正确"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 账号
|
||||
|
||||
### `POST /api/auth/login`
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
成功响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"user": {
|
||||
"id": 1,
|
||||
"email": "user@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 核心资源
|
||||
|
||||
把项目的核心资源按 REST 或其他风格写清楚。
|
||||
|
||||
### `GET /api/items`
|
||||
|
||||
成功响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "示例"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/items`
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "示例"
|
||||
}
|
||||
```
|
||||
|
||||
成功响应返回新增资源。
|
||||
|
||||
## 待实现时确认
|
||||
|
||||
- 参数校验规则。
|
||||
- 分页、排序、筛选方式。
|
||||
- 重复提交是否幂等。
|
||||
- 错误码枚举。
|
||||
- 鉴权过期时间和刷新策略。
|
||||
@@ -0,0 +1,63 @@
|
||||
# 当前实现状态
|
||||
|
||||
> 本文记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
|
||||
|
||||
## 当前快照
|
||||
|
||||
- 日期：【YYYY-MM-DD】
|
||||
- 阶段：【MVP 起步 / 原型验证 / 功能开发 / 上线前】
|
||||
- 技术栈：【简述当前已落地的技术栈】
|
||||
- 生产代码：【入口文件和关键目录】
|
||||
- 测试：【已有测试与命令】
|
||||
- 数据：【已有数据源或 seed 文件】
|
||||
|
||||
## 当前目录要点
|
||||
|
||||
| 路径 | 状态 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `docs/` | 已有 | 项目规范化文档 |
|
||||
| `src/` | 【已有 / 待建】 | 前端或核心代码 |
|
||||
| `server/` | 【已有 / 待建】 | 后端代码 |
|
||||
| `tests/` | 【已有 / 待建】 | 测试 |
|
||||
| `scripts/` | 【已有 / 待建】 | 辅助脚本 |
|
||||
|
||||
## 任务看板状态
|
||||
|
||||
以 [`06-tasks.md`](06-tasks.md) 为准。
|
||||
|
||||
- 已完成：【列出 DONE 任务】。
|
||||
- 正在进行：【如有，列出 DOING 任务】。
|
||||
- 下一个可领取任务：【第一个 TODO 且依赖均 DONE 的任务】。
|
||||
|
||||
## 当前可运行内容
|
||||
|
||||
```bash
|
||||
# 本地开发
|
||||
【命令】
|
||||
|
||||
# 测试
|
||||
【命令】
|
||||
|
||||
# 构建
|
||||
【命令】
|
||||
```
|
||||
|
||||
## 开始编码前检查
|
||||
|
||||
开始任意任务前：
|
||||
|
||||
1. 读仓库级 agent 规则文件（如有）。
|
||||
2. 读 `docs/00-ai-start-here.md`。
|
||||
3. 读 `docs/05-coding-rules.md`。
|
||||
4. 在 `docs/06-tasks.md` 取第一个 `TODO` 且依赖均 `DONE` 的任务。
|
||||
5. 将该任务状态改为 `DOING`。
|
||||
|
||||
## 维护规则
|
||||
|
||||
当实际代码状态发生变化时，同步更新本文件：
|
||||
|
||||
- 新增或移动入口文件。
|
||||
- 初始化框架或模块。
|
||||
- 任务从 `TODO` 进入 `DOING` 或 `DONE`。
|
||||
- 新增可运行命令。
|
||||
- 发现文档和代码现实不一致。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 路由与页面结构
|
||||
|
||||
> 本文约定前端页面路由、页面职责和组件归属。没有前端页面的项目，可改成 CLI 命令、后台任务或模块入口说明。
|
||||
|
||||
## 页面路由
|
||||
|
||||
| 路由 | 页面 | MVP 说明 |
|
||||
| --- | --- | --- |
|
||||
| `/` | 首页 / 列表页 | 展示主入口 |
|
||||
| `/items/{id}` | 详情页 | 展示单个资源详情 |
|
||||
| `/login` | 登录页 | 登录入口 |
|
||||
| `/settings` | 设置页 | 用户或系统配置 |
|
||||
|
||||
## 页面职责
|
||||
|
||||
### 首页 / 列表页
|
||||
|
||||
- 展示【核心资源列表】。
|
||||
- 支持【筛选 / 搜索 / 新建】。
|
||||
- 展示【状态 / 进度 / 空状态】。
|
||||
|
||||
### 详情页
|
||||
|
||||
- 根据 URL 参数定位资源。
|
||||
- 展示核心信息。
|
||||
- 支持 MVP 范围内的关键操作。
|
||||
- 异常时展示明确错误或降级状态。
|
||||
|
||||
### 登录页
|
||||
|
||||
- 通过账号 API 建立会话。
|
||||
- 登录成功后返回原目标页或首页。
|
||||
|
||||
## 组件建议
|
||||
|
||||
| 组件 | 归属 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `AppShell` | 全局 | 页面框架、导航、登录态入口 |
|
||||
| `ItemList` | 首页 | 渲染资源列表 |
|
||||
| `ItemDetail` | 详情页 | 渲染资源详情 |
|
||||
| `AuthForm` | 登录页 | 登录 / 注册表单 |
|
||||
|
||||
## 导航规则
|
||||
|
||||
- 首页进入详情页：点击资源项。
|
||||
- 详情页返回首页：保留返回入口。
|
||||
- 未登录访问需要账号的页面时，引导登录。
|
||||
- 权限不足时显示明确错误，不静默失败。
|
||||
Reference in New Issue
Block a user