2026-08-03 12:13:39 +08:00
|
|
|
|
# 项目文档导航
|
|
|
|
|
|
|
|
|
|
|
|
## 一句话定位
|
|
|
|
|
|
|
2026-08-03 16:27:05 +08:00
|
|
|
|
cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`）负责建单与人工决策，
|
|
|
|
|
|
**采购工具**（Windows 桌面端，`client/`）驱动 Android 手机在拼多多完成选规格和下单，
|
|
|
|
|
|
**付款始终由人完成**。第一版先跑通「手工建单 → 定时领取 → 第一趟试选 → 人工确认 →
|
|
|
|
|
|
第二趟下单 → 待付款」闭环。
|
2026-08-03 12:13:39 +08:00
|
|
|
|
|
|
|
|
|
|
## 文档导航
|
|
|
|
|
|
|
|
|
|
|
|
- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
|
|
|
|
|
|
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，规则以 `AGENTS.md` 为准。
|
|
|
|
|
|
- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序、任务领取规则，
|
|
|
|
|
|
以及**本项目的四条特有纪律**。
|
|
|
|
|
|
- [项目愿景](01-vision.md)：为什么做、为谁做、非目标、与前序项目的关系。
|
|
|
|
|
|
- [需求](02-requirements.md)：功能清单、验收标准、风险点。
|
|
|
|
|
|
- [用户故事清单](07-user-stories.md)：US 编号、用户目标与验收场景。
|
|
|
|
|
|
- [技术栈](03-tech-stack.md)：两端选型、运行命令、**验证矩阵**。
|
|
|
|
|
|
- [架构设计](04-architecture.md)：双端职责、**两趟执行**、**三道价格闸门**、安全边界、数据模型。
|
|
|
|
|
|
- [编码规则](05-coding-rules.md)：硬约束，第 1 节是本项目红线。
|
|
|
|
|
|
- [任务路线图](06-tasks.md)：阶段划分、里程碑、建议拆分清单。
|
|
|
|
|
|
- [任务文件](tasks/README.md)：一任务一文件约定与真机验收要求。
|
|
|
|
|
|
- [API 合约](api.md)：**双端之间的唯一权威**，含设备侧接口与本地模块合约。
|
2026-08-03 16:27:05 +08:00
|
|
|
|
- [路由与页面结构](routes.md)：采购服务页面路由与采购工具界面结构。
|
2026-08-03 12:13:39 +08:00
|
|
|
|
- [交互清单](08-interaction-checklist.md)：IX 编号、状态与异常清单、无障碍要求。
|
|
|
|
|
|
- [设计原型输入约定](design/README.md)：单文件 HTML 低保真原型的形态与边界。
|
|
|
|
|
|
- [当前实现状态](current-state.md)：当前快照、可运行命令、下一步任务、已知风险。
|
|
|
|
|
|
- [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) /
|
|
|
|
|
|
[Schema](agent-context.schema.json)：按任务类型选择文档。
|
|
|
|
|
|
- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查。
|
|
|
|
|
|
- [方法对照表](method-map.md)：失败模式 → 首要修复 → 工件。
|
|
|
|
|
|
- [评审评分表](evaluator-rubric.md)：单次会话输出的结构化评审。
|
|
|
|
|
|
- [质量文档](quality-document.md)：代码库长期健康度追踪。
|
|
|
|
|
|
- [`../scripts/validate_agent_context.py`](../scripts/validate_agent_context.py)：零依赖校验
|
|
|
|
|
|
上下文清单与仓库相对路径。
|
|
|
|
|
|
|
|
|
|
|
|
## 任务 / 状态职责
|
|
|
|
|
|
|
|
|
|
|
|
- `tasks/`（`docs/tasks/T-<编号>.md`）：任务规格、依赖、状态（frontmatter）和执行记录。
|
|
|
|
|
|
- `06-tasks.md`：路线图，阶段划分与里程碑，不跟踪单任务状态。
|
|
|
|
|
|
- `current-state.md`：当前快照，可覆盖更新。
|
|
|
|
|
|
|
|
|
|
|
|
## 必读的四处硬约束
|
|
|
|
|
|
|
|
|
|
|
|
新接手时如果只看四个地方，看这四个：
|
|
|
|
|
|
|
|
|
|
|
|
1. [`04-architecture.md`](04-architecture.md) **第三节两趟执行与三道价格闸门**——为什么
|
|
|
|
|
|
分两趟、价格为什么只在两个地方读。
|
|
|
|
|
|
2. [`04-architecture.md`](04-architecture.md) **第四节安全边界与提交订单四条件**——每条
|
|
|
|
|
|
都要有测试。
|
|
|
|
|
|
3. [`05-coding-rules.md`](05-coding-rules.md) **第 1 节红线**——违反即拒绝。
|
|
|
|
|
|
4. [`00-ai-start-here.md`](00-ai-start-here.md) **四条特有纪律**——先取证、只收紧、
|
|
|
|
|
|
只在两处读价、第一趟不下单。
|
|
|
|
|
|
|
|
|
|
|
|
## 维护原则
|
|
|
|
|
|
|
|
|
|
|
|
- 需求变化先改文档，再改代码。
|
|
|
|
|
|
- 代码现实变化后同步 `current-state.md`；执行证据写进对应任务文件。
|
|
|
|
|
|
- API、数据模型、路由、技术栈一旦定稿，代码不得另起一套。
|
|
|
|
|
|
- 前序项目 `cmroubao` / `cmpdd` 是设计依据，**不是事实来源**。
|
|
|
|
|
|
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
|
