cz-web/docs/dev-plan.md

开发规划 — cz-web（auto-dev 全流程跟踪表）

使用说明（工作规则）

1. 状态标记：[x] = 开发完成并验证通过；[~] = 开发中；[ ] = 未开始；[!] = 阻塞（注明原因）。
2. 每完成一项立即打 [x]（开发结束标记），不得批量补标。
3. 之后只做未完成（[ ]/[~]/[!]）的部分，已完成项不再重做，除非回归失败。
4. 每个模块收尾必须过 pnpm build（vue-tsc 零错误）才算可打 [x]。
5. 当前约束：无接口文档 → 接口细节 [!] 阻塞中；页面代码按 PRD + 原型降级开发（结构/交互先行，视觉参数用 styles/variables.less 近似值，接口用 store 层 mock 临时实现并集中标注 // TODO(api)，文档到位后仅替换 api 层）。
6. 蓝湖设计稿已到位（2026-09-30）：pid b0052b6c-4eaa-4709-b2d1-32cf4c1fe53b，共 55 张设计图（因 UI 失误全部命名为「首页」，已按标注图层文字 + 像素取证完成「设计图 → 路由」映射）；阶段二与「蓝湖视觉补齐」已完成。

阶段总览

阶段	内容	状态
阶段一	PRD 生成（docs/PRD.md）	[x]
阶段二	蓝湖 MCP 设计稿读取（标注参数/切图）	[x]（55 张标注已落盘 specs/*.ann.txt；lanhu_get_design_overview/export_design_assets 因 UnsupportedCoordinates 不可用，切图改由 2× 封面按标注坐标裁剪）
阶段三	页面结构规划（docs/page-architecture.md）	[x]
阶段四	页面代码生成 + 组件拆分	[x]
阶段五	API + Store 逻辑层	[x]
阶段六	公共组件提取	[x]
阶段七	自动验证与修正（pnpm build 零错误）	[x]
补齐	接口文档落地后替换 mock api 层	[!] 无接口文档，阻塞
补齐	蓝湖到位后校准视觉（色值/间距/字号/切图）	[x]

P0 基础工程（全模块前置）

• vite.config.ts：配置 @/ 别名、css.preprocessorOptions.less.additionalData 注入 variables.less、安装 less
• src/styles/：index.less + variables.less（色/字/间距/圆角近似值）+ mixins.less + reset.less + common.less
• src/types/api.d.ts：ApiResponse<T>、PageResult<T>、FileInfo
• src/types/router.d.ts：RouteMeta 扩展（title、requiresAuth）
• src/types/global.d.ts + src/env.d.ts
• src/utils/：request.ts（唯一 axios 实例 + 拦截器）、storage.ts、validate.ts、format.ts
• src/composables/：useCountDown.ts、useLoading.ts、useScroll.ts、useIntersection.ts
• src/directives/：lazy.ts、debounce.ts、throttle.ts、index.ts（setupDirectives）
• src/stores/index.ts（pinia 实例）+ stores/modules/site.ts（全局 loading/站点配置）
• src/router/index.ts + routes.ts + guard.ts（Home + 404 先行注册，其余路由随 M1–M10 各自注册步骤接入）
• src/layout/index.vue（AppHeader + router-view + AppFooter 骨架）
• src/components/：AppHeader.vue、AppFooter.vue、AppButton.vue、index.ts
• src/main.ts：注册 pinia/router/指令、引入 styles/index.less
• 验证：pnpm build 零错误（vue-tsc + vite build 通过；Playwright 冒烟：header/footer/占位页渲染正常，控制台 0 错误）

模块开发清单（每模块七步，完成即打 [x]）

M1 home（首页 + 业务详情）

• types/business/home.d.ts（含 cases.d.ts 案例实体与 api.d.ts BusinessType 共享枚举，首页案例卡提前复用）
• api/home.ts（getHomeStats、getBusinessLines、getFeaturedCases、getBusinessDetail）// TODO(api)
• stores/modules/home.ts（useHomeStore）
• views/home/index.vue + index.ts + cpns/（HomeWelcome、HomeStats、HomeQuickEntries、HomeBusinessCards、HomeCaseShowcase、HomeServiceTabs）
• views/home/detail.vue（业务详情）
• router 注册 / 与 /business/:type
• 复用检查 + pnpm build 通过（Playwright QA：首页六区块渲染、Tab 筛选生效、业务详情页内容完整、控制台 0 错误）

M2 cases（案例库）

• types/business/cases.d.ts（M1 已建，M2 直接复用）
• api/cases.ts（getCaseList、getCaseDetail、toggleFavorite、getCaseCounts）// TODO(api)（8 条 mock + 筛选/分页）
• stores/modules/cases.ts（useCasesStore：列表/筛选/分页/收藏）
• views/cases/index.vue + detail.vue + index.ts + cpns/（CasesFilter、CasesGrid、CaseDetailHeader、CaseRichText）
• 公共组件 CaseCard（M1 已建）、FilterPanel、PaginationBar 上移 components/
• router 注册 /cases、/cases/:id
• 复用检查 + pnpm build 通过（Playwright QA：4 组筛选 + 计数 8/4/2/1、筛选 8→4 卡 + chip 回显、详情四段富文本、收藏切换 + toast、控制台 0 错误）

M3 demand（需求提报）

• types/business/demand.d.ts
• api/demand.ts（submitDemand、saveDraft、uploadAttachment）// TODO(api)
• stores/modules/demand.ts（useDemandStore：表单态/草稿/提交）
• views/demand/index.vue + index.ts + cpns/（DemandStep1Business、DemandStep2Info、DemandStep3Confirm）
• 公共组件 StepForm、FileList、UploadArea、CaseCard 复用接入
• router 注册 /demand
• 复用检查 + pnpm build 通过

M4 login（登录/注册/找回密码）

• types/business/user.d.ts
• api/auth.ts（loginByAccount、loginBySms、sendSmsCode、register、resetPassword）// TODO(api)
• stores/modules/user.ts（useUserStore：token/用户信息/登录态）
• views/login/index.vue（登录）+ register.vue + reset.vue + index.ts + cpns/（LoginForm、SmsLoginForm、RegisterForm、ResetForm）
• 公共组件 SmsCodeInput、PasswordStrength 上移
• router 注册 /login、/register、/reset-password + guard.ts 登录守卫
• 复用检查 + pnpm build 通过

M5 project（项目中心）

• types/business/project.d.ts
• api/project.ts（getProjectList、getProjectDetail、uploadProjectFile、deleteProjectFile、submitAfterSales、cancelAfterSales）// TODO(api)
• stores/modules/project.ts（useProjectStore：列表/筛选/详情/文件/售后）
• views/project/index.vue + detail.vue + after-sales.vue + index.ts + cpns/（ProjectFilter、ProjectTable、ProjectInfoCard、ProjectTeam、ProjectMilestones、ProjectFiles、ProjectFinance、ProjectAfterSales、AfterSalesForm）
• 公共组件 StatusTag、FileList、StepForm 复用接入
• router 注册 /project、/project/:id、/project/:id/after-sales
• 复用检查 + pnpm build 通过

M6 contract（合同中心）

• types/business/contract.d.ts
• api/contract.ts（getContractList、getContractDetail、getSignQr、refreshSignQr）// TODO(api)
• stores/modules/contract.ts（useContractStore：列表/详情/签署二维码倒计时）
• views/contract/index.vue + detail.vue + sign.vue + index.ts + cpns/（ContractTable、ContractInfoCard、ContractSignPanel、SignSteps）
• 公共组件 QrCodePanel、StatusTag 复用接入
• router 注册 /contract、/contract/:id、/contract/:id/sign
• 复用检查 + pnpm build 通过

M7 finance（财务中心）

• types/business/finance.d.ts
• api/finance.ts（getFinanceStats、getBillList、getBillDetail、createPayment、getPayResult、getInvoiceList、applyInvoice、sendInvoiceEmail、getInvoiceTitles、createInvoiceTitle、updateInvoiceTitle、deleteInvoiceTitle、setDefaultTitle、exportReport）// TODO(api)
• stores/modules/finance.ts（useFinanceStore：概览统计/账单/支付/发票/抬头）
• views/finance/index.vue（概览）+ bills.vue + bill-detail.vue + pay.vue + pay-result.vue + invoices.vue + invoice-titles.vue + index.ts + cpns/（FinanceOverview、FinanceChart、BillTable、BillSummaryBar、BillPayPanel、PayMethodDialog、PayResult、InvoiceTable、InvoiceTitleCard、InvoiceTitleDialog）
• 公共组件 QrCodePanel、StatusTag、ConfirmDialog、PaginationBar 复用接入
• router 注册 /finance 及 6 个子路由
• 复用检查 + pnpm build 通过

M8 message（消息中心）

• types/business/message.d.ts
• api/message.ts（getMessageList、getMessageDetail、markAllRead、markRead）// TODO(api)
• stores/modules/message.ts（useMessageStore：列表/分类未读数/详情）
• views/message/index.vue + detail.vue + index.ts + cpns/（MessageTabs、MessageList、MessageItem、NoticeDetail）
• AppHeader 消息铃铛角标接入 message store
• router 注册 /message、/message/:id
• 复用检查 + pnpm build 通过

M9 service（在线客服）

• types/business/service.d.ts
• api/service.ts（getChatHistory、sendChatMessage、uploadChatFile）// TODO(api)
• stores/modules/service.ts（useServiceStore：会话/消息/发送）
• views/service/index.vue + index.ts + cpns/（ChatWindow、ChatMessageItem、ChatFileCard、ChatInput）
• 全局浮动「在线客服」入口接入
• router 注册 /service
• 复用检查 + pnpm build 通过

M10 profile（个人中心）

• types/business/profile.d.ts
• api/profile.ts（updateNickname、changePassword、bindPhone、unbindPhone、bindEmail、unbindEmail、deleteAccount、verifyIdentity、getAddresses、createAddress、updateAddress、deleteAddress、setDefaultAddress、getFavorites、getQualifications、createQualification、updateQualification、deleteQualification、submitFeedback）// TODO(api)
• stores/modules/profile.ts（useProfileStore：账号/地址/收藏/资质/反馈）
• views/profile/index.vue（左菜单布局）+ security.vue + address.vue + favorites.vue + qualifications.vue + feedback.vue + help.vue + about.vue + hotline.vue + index.ts + cpns/（ProfileSider、ProfileUserCard、SecurityPanel、ChangePasswordDialog、UnbindAccountDialog、AddressCard、AddressDialog、FavoritesGrid、QualificationCard、QualificationDialog、FeedbackForm、HelpFaq、AboutPanel、HotlinePanel）
• 公共组件 SmsCodeInput、PasswordStrength、ConfirmDialog、FileList 复用接入
• router 注册 /profile 嵌套 8 子路由
• 复用检查 + pnpm build 通过

收尾阶段

• 阶段六：全局扫描，跨页面重复 UI 上移 components/，更新 components/index.ts barrel
• 阶段七：逐页对照 PRD/原型自检（布局/交互/字段/组件拆分/规范合规：无 as any、页面不直接 import api）
• pnpm build（vue-tsc）全量零错误
• 蓝湖到位后：校准 variables.less 色值/字号/间距，替换切图，逐页对照设计稿修正（主色 #276fff→#1f67ef、内容强调 #024fff、灰阶对齐 #1f2937/#4b5563/#6b7280/#9ca3af、危险 #ef4444、成功 #16a34a、顶栏 #f4f5f9+#d8d8d8、页脚 #0c1321；AppHeader/AppFooter 按设计重写；10 个模块页面视觉按标注补齐，<script> 逻辑块零改动；26 条路由 QA 无横向溢出/无同色不可见文字；pnpm build 零错误）
• 仍无设计稿的 5 个路由（保持现状，待补设计后再次校准）：/project 列表、/cases/:id 案例详情、/finance/invoices 发票申请、/profile/favorites 收藏列表、/profile/hotline 专属客服热线
• 接口文档到位后：逐 api 文件替换 // TODO(api) 为真实路径/入参出参，走真实联调 → 补打 [x]

完成度速查

单元	状态
P0 基础工程	[x]
M1 home	[x]
M2 cases	[x]
M3 demand	[x]
M4 login	[x]
M5 project	[x]
M6 contract	[x]
M7 finance	[x]
M8 message	[x]
M9 service	[x]
M10 profile	[x]
阶段六 公共组件提取	[x]
阶段七 验证修正	[x]
蓝湖视觉补齐	[x]
接口联调补齐	[!]